home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d12
/
mflms101.arc
/
MFL_FUNC.MAN
< prev
next >
Wrap
Text File
|
1989-11-25
|
321KB
|
16,963 lines
TITLE_PG.FM - Thu 23 Nov 89 00:19 - Page 1:
The MicroFirm Function Library
for Microsoft C & Quick C
ver 1.01
Copyright 1988-89 by Robert B. Stout dba MicroFirm
portions Copyright 1986-87 by Stephen E. Margison
All rights reserved
---------------------------------------
LIBRARY FUNCTIONS IN ALPHABETICAL ORDER
---------------------------------------
AABORT.FNC - Thu 23 Nov 89 00:19 - Page 2:
NAME
aabort -- terminate a program
PROTOTYPED IN: mflsys.h
SYNOPSIS
void aabort(code);
int code; exit error code
DESCRIPTION
The program is aborted (using the common_exit() function) after sending
the BELL character to stderr. By using the common_exit() routine,
any common exit function which has been installed will be called.
EXAMPLE
aabort(0);
ANSISYS.FNC - Thu 23 Nov 89 00:19 - Page 3:
NAME
ansisys -- detects ANSI.SYS
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = v_init();
LOGICAL r; TRUE if ANSI.SYS is loaded,
FALSE if ANSI.SYS is not loaded,
ERROR if function failed
DESCRIPTION
The ansisys() function detects the presence of ANSI.SYS or compatible
device driver (e.g. ZANSI, FANSI, etc.) Note that ansisys() requires a PC
to be closely compatible with IBM at the BIOS interrupt level.
EXAMPLE
LOGICAL aflag;
if (ERROR == (aflag = ansisys()))
puts("can't tell if ANSI.SYS is loaded");
else printf("ANSI.SYS is%s loaded\n", aflag ? "" : "n't");
SEE ALSO: make_ansi()
ARGVAL.FNC - Thu 23 Nov 89 00:19 - Page 4:
NAME
argval -- convert an ASCII numerical string from an argument
PROTORYPED IN: mflstrng.h
SYNOPSIS
i = argval(string, dest, i);
int i; index into the current argument string
which is returned incremented to the
first character after the numerical string
char *string; the string containing the numerical value
int dest; destination for resultant integer value
DESCRIPTION
This function is primarily intended to parse command line arguments
containing numerical values into an integer. The function will
abort the program if the index points to a non-numeric digit
upon entry with an error message and the option character which
preceeds the index pointer.
Numeric values cannot exceed four characters without causing
potential damage to the program by overrunning the character
storage area.
EXAMPLE
assume argv[1] = "-M30C"
int i, value;
i = 2 /* i is incremented to '3' by other code */
i = argval(&argv[1], value, i);
after execution, i = 4 (pointing to 'C')
value = 30
argv[1] is unchanged
ATR2ANSI.FNC - Thu 23 Nov 89 00:19 - Page 5:
NAME
make_ansi -- translate video attributes to ANSI strings
PROTOTYPED IN: mflconio.h
SYNOPSIS
astring = make_ansi(vattr);
char *astring; the returned ANSI string
int vattr; video attribute
DESCRIPTION
Given a standard video attribute byte, make_ansi() tanslates it
into an ANSI control string.
EXAMPLE
char *astring;
astring = make_ansi(YELLOW+(BLUE<<4));
SEE ALSO: ansisys()
BADEXT.FNC - Thu 23 Nov 89 00:19 - Page 6:
NAME
badext -- report invalid filename extension and exit
PROTOTYPED IN: mflfiles.h
SYNOPSIS
void badext(ext);
char *ext;
DESCRIPTION
This function may be used when an invalid filename extension must
cause the termination of a program. It is called with the
offending extension as the argument string. An error message
is sent to stderr, and the program terminates via the aabort()
function of this library.
SEE ALSO: exttyp()
BITCLR.FNC - Thu 23 Nov 89 00:19 - Page 7:
NAME
BitClr -- clear n'th bit
DEFINED IN: mfldefs.h
SYNOPSIS
BitClr(data,posn);
void data; may be char, int, or long
int posn; bit position to reset to 0; 0 = LSB
DESCRIPTION
The BitClr() function resets a particular bit to zero for a char, int
or long data variable.
EXAMPLE
int flag;
int mask=0xf0; /* mask (binary) = 11110000 */
mask = BitClr(mask,14); /* mask (binary) = 10110000 */
SEE ALSO: BitSet(), BitTst()
BITSET.FNC - Thu 23 Nov 89 00:19 - Page 8:
NAME
BitSet -- set n'th bit
DEFINED IN: mfldefs.h
SYNOPSIS
BitSet(data,posn);
void data; may be char, int, or long
int posn; bit position to set to 1; 0 = LSB
DESCRIPTION
The bitset() function sets a particular bit to 1 for a char, int or
long variable.
EXAMPLE
int flag;
int mask=0xf0; /* mask (binary) = 11110000 */
mask = BitSet(mask,1); /* mask (binary) = 10110010 */
SEE ALSO: BitClr(), BitTst()
BITTST.FNC - Thu 23 Nov 89 00:19 - Page 9:
NAME
BitTst -- test n'th bit
DEFINED IN: mfldefs.h
SYNOPSIS
BitTst(data,posn);
void data; may be char, int, or long
int posn; bit position to return; 0 = LSB
DESCRIPTION
The BitTst() function returns the bit position of a particular bit
from a char, int or long variable.
EXAMPLE
int flag;
flag = BitTst(mask,4); /* flag = TRUE */
SEE ALSO: BitClr(), BitSet()
BLPR.FNC - Thu 23 Nov 89 00:19 - Page 10:
NAME
blpr -- write a character to LPT? through BIOS 17H
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = blpr(chr, num);
int r; returns status in low 8 bits
char chr; character to write
int num; printer number 0-2
DESCRIPTION
The blpr() function writes a character to LPT?. This assembly
language routine provides very low-level access to the LPT1 - LPT3
drivers in the ROM-BIOS. Because of this dependency upon the ROM-BIOS
Interrupt 17H, this function may not work on all compatibles. The
normal DOS channel PRN: is bypassed, as is any re-assignment of LPT?.
Normally, this routine is not used directly; rather, it is accessed
through the "pr" series subroutine calls.
Status bits are returned as follows: (meaning is with bit set)
bit 0 = time out
bit 1,2 are unused and should be ignored
bit 3 = I/O error
bit 4 = Printer Selected
bit 5 = Out of Paper
bit 6 = Acknowledged
bit 7 = Not Busy
EXAMPLE
int i;
i = blprstat(0); /* LPT1: is 0 */
if(!(i & 0x80)) puts("Printer is busy");
else blpr('A', 0);
SEE ALSO: blprstat
BLPRSTAT.FNC - Thu 23 Nov 89 00:19 - Page 11:
NAME
blprstat -- get LPT? status through BIOS 17H
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = blprstat(num);
int r; returns status in low 8 bits
int num; printer number 0-2
DESCRIPTION
The blprstat() function obtains printer status. This function
provides very low-level access to the LPT1 - LPT3 drivers in the
ROM-BIOS. Because of this dependency upon the ROM-BIOS Interrupt 17H,
this function may not work on all compatibles. The normal DOS channel
PRN: is bypassed, as is any re-assignment of LPT?. Normally, this
function are not used directly; rather, it is accessed through the
"pr" series subroutine calls.
Status bits are returned as follows: (meaning is with bit set)
bit 0 = time out
bit 1,2 are unused and should be ignored
bit 3 = I/O error
bit 4 = Printer Selected
bit 5 = Out of Paper
bit 6 = Acknowledged
bit 7 = Not Busy
EXAMPLE
int i;
i = blprstat(0); /* LPT1: is 0 */
if(!(i & 0x80)) puts("Printer is busy");
else blpr('A', 0);
SEE ALSO: blpr()
BPUTC.FNC - Thu 23 Nov 89 00:19 - Page 12:
NAME
Bputc -- write a character using BIOS only
DEFINED IN: mfldefs.h
SYNOPSIS
Bputc(character);
char character; character to write
DESCRIPTION
Since DOS is not re-entrant, you cannot (in general) call DOS
functions from within interrupt handlers, including Ctrl-Break and
critical error handlers as supported by ctlbrk() or criterr(). This
function works identically to fputc(stderr) except that it writes
directly to the screen via BIOS, bypassing all DOS calls. The only
caution is that writing a '\n' using Bputc only causes a line feed.
To achieve the normal (for C) newline function, you must either
explicitly write an additional '\r' or simply use Bputs("\n")
instead.
EXAMPLE
Bputc('\a');
SEE ALSO: Bputs(), ctlbrk(), criterr()
BPUTS.FNC - Thu 23 Nov 89 00:19 - Page 13:
NAME
Bputs -- write a string using BIOS only
PROTOTYPED IN: mflconio.h
SYNOPSIS
Bputs(string);
char *string; string to write
DESCRIPTION
Since DOS is not re-entrant, you cannot (in general) call DOS
functions from within interrupt handlers, including Ctrl-Break and
critical error handlers as supported by ctlbrk() or criterr(). This
functions works identically to fputs(stderr) except that it writes
directly to the screen via BIOS, bypassing all DOS calls. Note that
newline characters are properly translated into CR-LF pairs.
EXAMPLE
Bputs("Something's wrong!\n");
SEE ALSO: Bputc
CANT.FNC - Thu 23 Nov 89 00:19 - Page 14:
NAME
cant -- report inability to open a file and exit
PROTOTYPED IN: mflfiles.h
SYNOPSIS
void cant(name);
char *name; filename to display
DESCRIPTION
This function is used to report a failure to open a file of
"name", and then abort the program through the aabort() function
of this library.
EXAMPLE
cant("foo.bar");
cant(argv[1]);
CENTER.FNC - Thu 23 Nov 89 00:19 - Page 15:
NAME
center -- center a string
PROTOTYPED IN: mflstrng.h
SYNOPSIS
r = center(string, size);
int r; starting column for centering
char *string; string to center
int size; width of field for centering
DESCRIPTION
This function returns the starting column to print a string for the
string to be centered in a field of "size" characters. For the
screen, the width would usually be 80, and for printers, either 80 or
132. The string MUST NOT BE longer than the size specified, since
there is no error cheking for this condition and an unusable result
will be returned.
EXAMPLE
char title[] = "Title of Program";
main() {
int i;
i = center(title, 80);
d_say(2, i, title); /* display title centered in row 2 */
}
CHDRV.FNC - Thu 23 Nov 89 00:19 - Page 16:
NAME
chdrv -- change disk drives
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = chdrv(drive);
int r; returns ERROR if drive is invalid
char drive; drive ('A' - 'Z') to check
DESCRIPTION
Chdrv() as an anlog of the chdir() function which changes drives
rather than directories. It is not necesary, when using chdrv(), to
validate the target drive using drvalid() since this is done
automatically by chdrv().
EXAMPLE
char drive;
if ('C' != drive) {
if (!chdrv('C'))
puts("changed to drive C:");
else puts("\aunable to change drives");
}
SEE ALSO: getdrv(), drvalid()
CHKCTS.FNC - Thu 23 Nov 89 00:19 - Page 17:
NAME
chkcts -- check state of clear to send flag
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = chkcts(port);
int r; TRUE or FALSE, depending upon state
int port; 0, 1, 2, or 3 (for COM1-COM4)
DESCRIPTION
This function is part of a set of assembly language functions which
provide direct access to the serial communications chips for the
fastest access possible. Calling chkcts() checks the status of the
clear to send and returns its state as TRUE (on) or FALSE (off).
The port parameter may be specified as integers 0-3, or SER1 to SER4
as defined in <mflsys.h>.
EXAMPLE
int sport; /* serial port */
sport = SER2; /* let it point to COM2 */
if(chkdcd(sport)) puts("Ok to send");
else puts("Don't send data now");
SEE ALSO: chkdcd(), chkdsr(), chkring()
CHKDCD.FNC - Thu 23 Nov 89 00:19 - Page 18:
NAME
chkdcd -- check state of carrier detect flag
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = chkdcd(port);
int r; TRUE or FALSE, depending upon state
int port; 0, 1, 2, or 3 (for COM1-COM4)
DESCRIPTION
This function is part of a set of assembly language functions which
provide direct access to the serial communications chips for the
fastest access possible. Calling chkdcd() checks the status of the
carrier detect flag and returns its state as TRUE (on) or FALSE (off).
The port parameter may be specified as integers 0-3, or SER1 to SER4
as defined in <mflsys.h>.
EXAMPLE
int sport; /* serial port */
sport = SER2; /* let it point to COM2 */
if(chkdcd(sport)) puts("We have a carrier detected");
else puts("The modem is apparently idle");
SEE ALSO: chkdsr(), chkcts(), chkring()
CHKDSR.FNC - Thu 23 Nov 89 00:19 - Page 19:
NAME
chkdsr -- check state of data set ready flag
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = chkdsr(port);
int r; TRUE or FALSE, depending upon state
int port; 0, 1, 2, or 3 (for COM1-COM4)
DESCRIPTION
This function is part of a set of assembly language functions which
provide direct access to the serial communications chips for the
fastest access possible. Calling chkdsr() checks the status of the
data set ready flag and returns its state as TRUE (on) or FALSE (off).
The port parameter may be specified as integers 0-3, or SER1 to SER4
as defined in <mflsys.h>.
EXAMPLE
int sport; /* serial port */
sport = SER2; /* let it point to COM2 */
if(chkdsr(sport)) puts("DSR flag is set");
else puts("DSR flag is not set");
SEE ALSO: chkdcd(), chkcts(), chkring()
CHKRING.FNC - Thu 23 Nov 89 00:19 - Page 20:
NAME
chkring -- check state of ring indicator flag
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = chkring(port);
int r; TRUE or FALSE, depending upon state
int port; 0, 1, 2, or 3 (for COM1-COM4)
DESCRIPTION
This function is part of a set of assembly language functions which
provide direct access to the serial communications chips for the
fastest access possible. Calling chkring() checks the status of the
ring indicator flag and returns its state as TRUE (on) or FALSE (off).
The port parameter may be specified as integers 0-3, or SER1 to SER4
as defined in <mflsys.h>.
EXAMPLE
int sport; /* serial port */
sport = SER2; /* let it point to COM2 */
if(chkring(sport)) puts("Ring indicator flag is set");
else puts("Ring indicator flag is not set");
SEE ALSO: chkdcd(), chkdsr(), chkcts()
CLR_GAME.FNC - Thu 23 Nov 89 00:19 - Page 21:
NAME
clr_game() --- clear pending input from game port
PROTOTYPED IN: mflsys.h
SYNOPSIS
(void)clear_game();
DESCRIPTION
Calling clear_game() clears any pending input and forces the debouncer
to assume a new input sequence.
EXAMPLE
main() {
unsigned char i;
init_game(FALSE); /* allow only single switch inputs */
for ever() {
debounce(); /* call this regularly */
i = get_press();
if(i is 0) continue;
printf("switch value is %x\n", i);
}
}
SEE ALSO: init_game(), getpress(), debounce()
CLRCAPS.FNC - Thu 23 Nov 89 00:19 - Page 22:
NAME
clrcaps() -- sets Caps lock to OFF
PROTOTYPED IN: mflconio.h
SYNOPSIS
clrcaps();
DESCRIPTION
This function forces the caps lock status flag to OFF.
EXAMPLE
setcaps();
if(kbstate(2)) puts("Caps lock is now set");
else puts("Caps lock is NOT set");
clrcaps();
puts("Caps lock should now be off");
SEE ALSO: _kbstate(), kbstatus(), setcaps(), clrcaps(), setnumlock(),
clrnumlock()
CLRFIELD.FNC - Thu 23 Nov 89 00:19 - Page 23:
NAME
clrfield -- clear a screen field through BIOS
PROTOTYPED IN: mflconio.h
SYNOPSIS
void clrfield(row, col, size, page);
int row, col; starting point
int size; number of columns to clear ( <= 80)
int page; video page number
(for non-CGA, specify 0)
DESCRIPTION
This function handles the problem of clearing a section of a line on
the screen without clearing to the end of the line. If the size
parameter is larger than 80, it is forced to 80.
EXAMPLE
clrfield(10, 20, 15, 0); /* clear 15 columns on page 0
starting at row 10, column 20 */
SEE ALSO: disp_clrfield
CLRNMLOC.FNC - Thu 23 Nov 89 00:19 - Page 24:
NAME
clrnmloc() --- turns numlock off
PROTOTYPED IN: mflconio.h
SYNOPSIS
clrnumlock();
DESCRIPTION
This function forces the numlok status flag to OFF.
EXAMPLE
setnumlok();
if(kbstate(2)) puts("Num lock is now set");
else puts("Num lock is NOT set");
clrnumlock();
puts("Num lock should now be off");
SEE ALSO: _kbstate(), kbstatus(), setcaps(), clrcaps(), setnumlock(),
clrnumlock()
CLS.FNC - Thu 23 Nov 89 00:19 - Page 25:
NAME
cls -- clear screen and home cursor
PROTOTYPED IN: mflconio.h
SYNOPSIS
void cls();
DESCRIPTION
This function clears the screen on page 0 and places the
cursor in the upper left-hand corner. It is simply an
invocation of two other functions:
d_cls();
d_pos(0, 0, 0);
EXAMPLE
cls();
SEE ALSO: d_cls()
CLSDIR.FNC - Thu 23 Nov 89 00:19 - Page 26:
NAME
closedir -- close a directory
PROTOTYPED IN: mflfiles.h
SYNOPSIS
void closedir(d1);
DOS_DIR *d1; directory file pointer
DESCRIPTION
The closedir() function closes the open directory whose file pointer
is passed, just as fclose() closes normal DOS files.
EXAMPLE
char *name[] = "C:\looney\bin";
DOS_DIR *dirp;
struct FIND *ffblk;
if(dirp=opendir(name))
{
printf("%s contains %d entries\n", name, dirp->dd_size);
while (ffblk=readdir(dirp))
{
printf("%3d - %s\n", dirp->dd_loc, ffblk->name);
}
closedir(dirp);
}
SEE ALSO: readdir(), opendir()
CRC2CLR.FNC - Thu 23 Nov 89 00:19 - Page 27:
NAME
crc16_clr() --- clear crc value
PROTOTYPED IN: mflmath.h
SYNOPSIS
r = crc16_clear();
unsigned r; 16-bit crc to clear
DESCRIPTION
This function is part of a group of functions used to do crc
calculations. crc16_clear is used to clear the crc value. However,
if speed is a concern, just zero the crc value since crc16_clear
does nothing other than return a zero.
EXAMPLE
unsigned crc;
crc = crc16_clear();
/* for each character processed: */
crc = crc16_update(crc, next_chr);
/* finally, */
crc = crc16_finish;
NOTE:
These functions are from a public domain source, author unknown, They
are not copyrighted.
SEE ALSO: crc16_update(), crc16_finish(), crc32_clear() crc32_update(),
crc32_finish()
CRC2FNSH.FNC - Thu 23 Nov 89 00:19 - Page 28:
NAME
crc16_finish() --- finish crc calculation
PROTOTYPED IN: mflmath.h
SYNOPSIS
r = crc16_finish(crc);
unsigned r; final 16-bit crc value
unsigned crc; old 16-bit crc value
DESCRIPTION
This function is part of a group of functions used to do crc
calculations. Calling crc16_finish() crc16_finish actually calls
crc16_update twice with a value of 0 in order to flush the 16 bit
calculation and return the final crc calculation. As supplied, the
CCITT calculation polynomial is used. The source can be easily
changed to CRC16 if desired.
EXAMPLE
unsigned crc;
crc = crc16_clear();
/* for each character processed: */
crc = crc16_update(crc, next_chr);
/* finally, */
crc = crc16_finish;
NOTE:
These functions are from a public domain source, author
unknown, They are not copyrighted.
SEE ALSO: crc16_clear(), crc16_update(), crc32_clear(), crc32_update(),
crc32_finish()
CRC2UPDT.FNC - Thu 23 Nov 89 00:19 - Page 29:
NAME
crc16_update() --- update crc value
PROTOTYPED IN: mflmath.h
SYNOPSIS
r = crc16_update(crc, chr);
unsigned r; new 16-bit crc value
unsigned crc; old 16-bit crc value
char chr; datum
DESCRIPTION
This function is part of a group of functions used to do crc
calculations. crc16_update is called once for each character to add to
the crc. It receives the running crc and the character to be added. As
supplied, the CCITT calculation polynomial is used. The source can be
easily changed to CRC16 if desired.
EXAMPLE
unsigned crc;
crc = crc16_clear();
/* for each character processed: */
crc = crc16_update(crc, next_chr);
/* finally, */
crc = crc16_finish;
NOTE:
These functions are from a public domain source, author unknown, They
are not copyrighted.
SEE ALSO: crc16_clear(), crc16_finish(), crc32_clear(), crc32_update(),
crc32_finish()
CRC4CLR.FNC - Thu 23 Nov 89 00:19 - Page 30:
NAME
crc32_clr() --- clear crc value
PROTOTYPED IN: mflmath.h
SYNOPSIS
r = crc32_clear();
unsigned long r; 32-bit crc to clear
DESCRIPTION
This function is part of a group of functions used to do crc
calculations. crc32_clear is used to clear the crc value. However,
if speed is a concern, just zero the crc value since crc32_clear
does nothing other than return a zero.
EXAMPLE
unsigned long crc;
crc = crc32_clear();
/* for each character processed: */
crc = crc32_update(crc, next_chr);
/* finally, */
crc = crc32_finish;
NOTE:
These functions are from a public domain source, author unknown, They
are not copyrighted.
SEE ALSO: crc32_update(), crc32_finish(), crc16_clear(), crc16_update(),
crc16_finish()
CRC4FNSH.FNC - Thu 23 Nov 89 00:19 - Page 31:
NAME
crc32_finish() --- finish crc calculation
PROTOTYPED IN: mflmath.h
SYNOPSIS
r = crc32_finish(crc);
unsigned long r; final 32-bit crc value
unsigned long crc; old 32-bit crc value
DESCRIPTION
This function is part of a group of functions used to do crc
calculations. Calling crc32_finish() crc32_finish actually calls
crc32_update twice with a value of 0 in order to flush the 16 bit
calculation and return the final crc calculation. As supplied, the
CCITT calculation polynomial is used. The source can be easily
changed if desired.
EXAMPLE
unsigned long crc;
crc = crc32_clear();
/* for each character processed: */
crc = crc32_update(crc, next_chr);
/* finally, */
crc = crc32_finish;
NOTE:
These functions are from a public domain source, author
unknown, They are not copyrighted.
SEE ALSO: crc32_clear(), crc32_update(), crc16_clear(), crc16_update(),
crc16_finish()
CRC4UPDT.FNC - Thu 23 Nov 89 00:19 - Page 32:
NAME
crc32_update() --- update crc value
PROTOTYPED IN: mflmath.h
SYNOPSIS
r = crc32_update(crc, chr);
unsigned long r; new 32-bit crc value
unsigned long crc; old 32-bit crc value
char chr; new datum
DESCRIPTION
This function is part of a group of functions used to do crc
calculations. crc32_update is called once for each character to add to
the crc. It receives the running crc and the character to be added. As
supplied, the CCITT calculation polynomial is used. The source can be
easily changed to CRC16 if desired.
EXAMPLE
unsigned long crc;
crc = crc32_clear();
/* for each character processed: */
crc = crc32_update(crc, next_chr);
/* finally, */
crc = crc32_finish;
NOTE:
These functions are from a public domain source, author unknown, They
are not copyrighted.
SEE ALSO: crc32_clear(), crc32_finish(), crc16_clear(), crc16_update(),
crc16_finish()
CRYPT.FNC - Thu 23 Nov 89 00:19 - Page 33:
NAME
crypt -- encrypt/decrypt data
PROTOTYPED IN: mflsys.h
SYNOPSIS
crypt(buf);
char *buf; datum to encrypt
DESCRIPTION
crypt implements a fully-reversible encryption algorithm
which is simultaneously simple and fast, yet reasonably
secure. The algorithm used is compatible with both the LYNX
and CRYPT utilities of the MicroFirm Toolkit, ver 3.00 or
later, and the crypt function of the CXL windowing library.
EXAMPLE
/* following externs declared in MFLSYS.H */
extern char *cryptext; /* the encryption key */
extern int crypt_ptr;
extern int crypt_length;
char *buf; /* data to encrypt */
crypt_ptr = 0; /* reset key pointer */
crypt_length = strlen(cryptext);
while (*buf) {
*buf = crypt(*buf);
++buf;
}
SEE ALSO: crypt_install(), cryptqual()
CRYPTQUL.FNC - Thu 23 Nov 89 00:19 - Page 34:
NAME
cryptqual -- qualify an encryption key
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = cryptqual(key, keyl);
LOGICAL r; SUCCESS if key qualifies, else ERROR
char *key; prospective encryption key to test
int keyl; number of unique characters required to qualify
key (range 1-26)
DESCCRIPTION
Although the C-CODER algorithm implemented in crypt() and fcrypt() is
capable of secure data encryption, it may be compromised by a poor
choice of encryption key. While there's no way to protect from a poor
judgement choice, the key may be qualified using the cryptqual()
function to verify that it contains a sufficient number of unique
characters. For example if 6 characters are required, "xxxxxx" would
fail while "switch" would qualify.
EXAMPLE
char *key;
/* "readers" fails - only 5 unique characters */
printf("%s %s\n", "readers",
cryptqual("readers, 6) ? "failed" : "passed");
/* "spreaders" qualifies - 6 unique characters */
printf("%s %s\n", "spreaders",
cryptqual("spreaders, 6) ? "failed" : "passed");
SEE ALSO: crypt(), crypt_install()
CTLBRK.FNC - Thu 23 Nov 89 00:20 - Page 35:
NAME
ctlbrk -- control-break (^C) interrupt handler
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = ctlbrk(func);
int *func;
int r; return 0 to continue program, not zero
to abort.
DESCRIPTION
This function is used to install a user-written interrupt handler for
DOS int 23h, the Control-C handler. The default handler simply exits
(ungracefully) the host program. Using ctlbrk(), a user-written
handler may be substituted for the default. This may be desirable if
it is absolutely necessary to prevent an untimely user-inspired exit,
or if control-C is desired to perform some function within the
program. The parameter passed is the address of the actual function.
Passing a NULL parameter re-installs the handler which was in the
interrupt table before this function altered the vector address. DOS
re-installs the original handler upon any program exit, so it is
unnecessary to uninstall this handler before actually exiting.
EXAMPLE
#include <stdio.h>
#include <keys.h>
handler()
{ Bputs("Control-C Received!!!\n");
/* couldn't use puts() which calls DOS */
return(0); /* continue program */
}
main()
{ char ch;
ctlbrk(&handler);
ch = NULL;
while(ch != ESC) /* loop until ESCAPE pressed */
ch = getche();
puts("Exiting program now. Have a nice day!");
}
WARNING:
Within the handler routine, keep the code simple and fast.
DO NOT use printf() or its relatives as these will destroy
the interrupt structure (for rather obscure reasons).
CURSOR.FNC - Thu 23 Nov 89 00:20 - Page 36:
NAME
cursor_style -- alter the cursor style
PROTOTYPED IN: mflconio.h
SYNOPSIS
void cursor_style(type, startscan, stopscan);
int type; type of cursor as defined below
int startscan; top scanline of cursor
int stopscan; bottom scanline of cursor
DESCRIPTION
This function allows selection of several pre-defined cursor
styles, or user-specified cursor size. If "type" is 0, then
user must supply a starting scanline and stopping scanline
value. If "type is 1-5, then these values may be set to
anything to simply satisfy the argument count. Cursor
scanlines are numbered from the top (0) to the bottom, which
is 7 for CGA boards, and 13 for Monochrome Adapters. The
Predefined values are:
type == 1 Normal underline cursor for CGA
type == 2 same, Mono Adapter
type == 3 Block cursor for CGA
type == 4 same, Mono Adapter
type == 5 Cursor becomes invisible
EXAMPLE
/* for CGA video modes: */
cursor_style(4, 0, 0); /* set block cursor */
cursor_style(1, 0, 0); /* restore underline cursor */
cursor_style(0, 1, 7); /* set a very large block cursor */
D_CLS.FNC - Thu 23 Nov 89 00:20 - Page 37:
NAME
d_cls -- clear current screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
void d_cls();
DESCRIPTION
This function clears the screen on the current page.
EXAMPLE
d_cls();
SEE ALSO: cls()
D_POS.FNC - Thu 23 Nov 89 00:20 - Page 38:
NAME
d_pos -- position the cursor on a video page
PROTOTYPED IN: mflconio.h
SYNOPSIS
void d_pos(r, c, p);
int r; row number
int c; column number
int p; video page (must match current mode)
DESCRIPTION
This function positions the cursor on the specified video
page. Row, column, and page values must match the current
video mode.
EXAMPLE
d_pos(10, 15, 0); /* position cursor on row 10, column 15,
video page 0 */
D_SAY.FNC - Thu 23 Nov 89 00:20 - Page 39:
NAME
d_say -- display a string at a specific position
PROTOTYPED IN: mflconio.h
SYNOPSIS
void d_say(r, c, str);
int r; row number
int c; column number
char *str; character string to display
DESCRIPTION
This function positions the cursor on the specified row and column on
video page 0, and then writes the string.
EXAMPLE
d_say(10, 15, "Hello World!\n");
CAVEAT: The string is written to stdout. Therefore, the results will
not be as advertised if stdout has been redirected from the
default video output. Video page selection is only available
on CGA adapters.
SEE ALSO: d_saypag
D_SAYPAG.FNC - Thu 23 Nov 89 00:20 - Page 40:
NAME
d_saypag -- position cursor with page specification, the write
PROTOTYPED IN: mflconio.h
SYNOPSIS
void d_saypag(r, c, str, p);
int r; row number
int c; column number
char *str; character string to display
int p; video page (must match current mode)
DESCRIPTION
This function positions the cursor on the specified row and column on
video page 0, and then writes the string. The d_saypag function also
selects the video page on which to place the cursor.
EXAMPLE
d_saypag(5, 20, "Goodby!", 1);
CAVEAT: The string is written to stdout. Therefore, the results will
not be as advertised if stdout has been redirected from the
default video output. Video page selection is only available
on CGA adapters.
SEE ALSO: d_say()
DAYNUM.FNC - Thu 23 Nov 89 00:20 - Page 41:
NAME
daynum -- find the number of a date within a year
PROTOTYPED IN: mfltime.h
SYNOPSIS
value = daynum(month, day, year);
int value; number 1-366
int month; month number 1-12
int day; date of the month 1-31
int year; year, starting at 1980
DESCRIPTION
This function returns the day number, 1-366, for the given
date. By itself, this is not very useful, but the function is
used as an intermediate calculation in certain other date routines.
Years below 1980 are ignored. The year value is used to determine
status as leap year.
EXAMPLE
for July 2, 1986:
int value;
value = daynum(7, 2, 1986);
SEE ALSO: julian_to_yrday()
DEBOUNCE.FNC - Thu 23 Nov 89 00:20 - Page 42:
NAME
debounce() -- input debouncer
PROTOTYPED IN: mflsys.h
SYNOPSIS
(void)debounce(); input debouncer
DESCRIPTION
This function is part of a series of functions used to read and
debounce the four switch inputs on the joystick input port. The
analog joystick inputs are not supported. debounce() must be called
periodically in order to debounce and process the switch inputs. It
is suggested that debounce() be called about 75 to 100 times per
second. The structure "gamesw" contains information used by these
routines. The number of times debounce must be invoked to return a
valid input is contained in gamesw.seed, and may be altered as
desired.
Switch values are returned as an 8 bit value, with only the lowest 4
bits in use. A set bit indicates a closed switch. If multiple
keystrokes are not allowed, then get_press() will return 0, 1, 2, 4,
or 8. If multiples are allowed, then all values 0-15 (0-0x0f) may be
returned.
bit position pin number on connector
0 2
1 7
2 14
3 10
EXAMPLE
main() {
unsigned char i;
init_game(FALSE); /* allow only single switch inputs */
for ever() {
debounce(); /* call this regularly */
i = get_press();
if(i is 0) continue;
printf("switch value is %x\n", i);
}
}
SEE ALSO: init_game(), clear_game(), get_press()
DELFILES.FNC - Thu 23 Nov 89 00:20 - Page 43:
NAME
del_files -- delete files using FCB functions
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = del_files(dir,mask);
int r; ERROR if directory could not be located, else
SUCCESS
char *dir; directory where files are located
char *mask; filename mask
DESCRIPTION
Using standard C functions such as find first/next and unlink() to delete
multiple files is dramatically slower than when COMMAND.COM does it. It
turns out that the speed advantage is due to the use of the FCB delete
call which can accept wildcards. The del_files() function works the same
way as COMMAND.COM and can wipe out whole directories full of files in a
flash.
EXAMPLE
char *path="C:\PATH\BRANCH", *mask="*.BAK";
if (ERROR == delfiles(path,mask))
printf("Couldn't find %s\n", path);
else printf("Files matching %s in %s deleted\n", mask, path);
SEE ALSO: unlink()
DIRMASK.FNC - Thu 23 Nov 89 00:20 - Page 44:
NAME
dirmask -- vaidate directory entry w/ name and attribute masks
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = dirmask(ffblk, y_mask, n_mask, y_atr, n_atr);
int r; SUCCESS if entry validated, else ERROR
struct FIND *ffblk; directory entry to validate
char *y_mask; name inclusion mask - validate if this
name matches the entry's - NULL matches
all
char *n_mask; name exclusion mask - validate if this
name does not matches the entry's - NULL
matches none
unsigned y_atr; attribute inclusion mask - FA_ANY
matches all
unsigned n_atr; attribute exclusion mask - 0 matches
none
DESCRIPTION
The dos_findfirst/next functions provide no convenient way to do
exclusion searches or to validate file attributes. For example if you
try looking for directories using findfirst and an attribute of
FA_DIREC, you'll soon find that DOS returns all directories PLUS all
normal files. The dirmask() function operates on a FIND structure to
validate its name and attribute members.
The first parameter is a file spec which must match for the directory
entry to be validated. The second is a file spec which will prevent
validation. The third parameter is an attribute mask which must match
the entry's attributes for validation. The fourth is an attribute mask
which will prevent validation. Specifying NULL for either of the name
specs will cause the corresponding validation to be skipped. Specifying
FA_ANY for the inclusion attribute will match all entries. Specifying 0
for the exclusion attribute will cause no entries to be rejected.
DIRMASK.FNC - Thu 23 Nov 89 00:20 - Page 45:
EXAMPLE
DOS_DIR *dirp;
struct FIND *ffblk;
/* print all non-.OBJ files beginning with 'A'...
...with the archive bit set which aren't directories */
dirp = opendir(fname);
do
{ if (NULL != (ffblk = readdir(dirp)))
{ if (SUCCESS == dirmask(ffblk, "A.*", "*.OBJ",
FA_ARCH ,FA_DIREC);
printf("%3d - %s\n", dirp->dd_loc, ffblk->name);
}
} while (ffblk);
puts("EOF\n");
closedir(dirp);
SEE ALSO: wildname(), opendir(), readdir() closedir(), rfind_1st(),
rfind_nxt()
DRVALID.FNC - Thu 23 Nov 89 00:20 - Page 46:
NAME
drvalid -- see if a drive is valid
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = drvalid(drive);
int r; returns TRUE if valid, else FALSE
char drive; drive ('A' - 'Z') to check
DESCRIPTION
Drvalid() tests if a specified drive is valid. FALSE will be returned
for non-existent drives or for a floppy drive with the door open or
with an unformatted diskette. This function works by attempting to do
an absolute disk read of sector zero and avoids the DOS critical error
(ABORT, RETRY, etc.) handler.
Note that the drive specification passed to drvalid() may be either
upper or lower case.
EXAMPLE
char drive;
if(drvalid('a')) puts("Drive valid!");
else puts("Drive not currently valid!");
SEE ALSO: getdrv, chdrv
DSTR_I.FNC - Thu 23 Nov 89 00:20 - Page 47:
NAME
dstr_i -- make an ascii decimal string into an integer
PROTOTYPED IN: mflstrng.h
SYNOPSIS
c = dstr_i(p, r);
char *p;
int *r;
int c;
DESCRIPTION
Read a string of ascii decimal digits and create an integer
from the result. String must begin with a digit, +, or -.
Calculation proceeds to first non-ascii digit or NULL terminator.
Count of actual digits read is returned, and integer is placed
in specified destination. '-' sign as first character returns
integer negated.
EXAMPLE
char string[] = "1357";
int result;
int count;
count = dstr_i(string, &result);
/* count will equal 4
result will equal 1357 */
DV_ATTR.FNC - Thu 23 Nov 89 00:20 - Page 48:
NAME
dvid_attrib -- set direct video attribute (color)
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_attrib(attrib);
int attrib; video attribute to set
DESCRIPTION
The dvid_attrib() function sets the video attribute used for subsequent
memory writes. The direct video access functions are described in some
detail in the users manual accompanying the MicroFirm Function Library.
They are only briefly reviewed here. Be sure to look at the utility
file "dump.c" for examples of function usage.
SEE ALSO: dvid_getattr()
DV_BIOS.FNC - Thu 23 Nov 89 00:20 - Page 49:
NAME
dvid_bios() -- force use of bios routines
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_bios(void);
DESCRIPTION
The dvid_bios() function may be called to force use of ROM BIOS services
if problems are encountered using memory access. The direct video
access functions are described in some detail in the users manual
accompanying the MicroFirm Function Library. They are only briefly
reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
DV_BOX.FNC - Thu 23 Nov 89 00:20 - Page 50:
NAME
dvid_box -- display a box on the screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
void dvid_box(row, col, width, height, style);
int row, col; position to display upper left corner
int height, width; size of box
int style; 0 = single line, 1 = double line,
2 = single line reverse video,
3 = double line reverse video
DESCRIPTION
This function uses the features of the MicroFirm Function Library
display package functions, and must therefore follow the rules laid
down for their use. Specifically, disp_init() must be called prior to
using this function, and the functions may fail of the target system is
not a very close compatible since direct memory writing is being used.
dvid_box places a single line or double line box on the screen with the
upper left corner anchored at "row" and "column", with the size denoted
by the "height" and "width" values. No error checking is done on any
value. Invalid values may have unpredictable results.
EXAMPLE
int i;
dvid_init(); /* initialize the package */
dvid_cls(); /* clear the screen */
dvid_box(0, 0, 80, 24, 1); /* border the entire screen */
/* with double graphics line */
CAVEAT:
if a color attribute has been set before this call,
it will revert to black & white if the "reverse video"
outlines are selected. The attribute is not changed
for the normal video border selections.
SEE ALSO: mkbox()
DV_CATR.FNC - Thu 23 Nov 89 00:20 - Page 51:
NAME
dvid_char_atr -- dvid_char_at, returns cursor to start
PROTOTYPED IN: mflconio.h
SYNOPSIS
void dvid_char_atr(row, col, char);
int row, col; position to display
char *string; string to display
char ch; character to display
DESCRIPTION
This function uses the features of the MicroFirm Function Library's
display package functions, and therefore, must follow the rules laid
down for their use. Specifically, dvid_init() must be called prior to
using this function, and the function may fail if the target system is
not a very close compatible since direct memory writing is being used.
dvid_char_atr() read the current real cursor position and perform a
dvid_move() after writing the specified data. Before using this call,
be sure the display package cursor position and the screen position are
equal by doing a dvid_flush() call.
EXAMPLE
int i;
dvid_init(); /* initialize the package */
dvid_cls(); /* clear the screen */
dvid_say(0, 0, "Hello"); /* write to upper left corner */
for(i = 0; i < 10; i++) {
dvid_char_at(i, i+1, i | '0'); /* write a sequence */
}
dvid_move(12, 40); /* move to center of screen */
dvid_flush(); /* physically update screen cursor */
dvid_sayr(20, 70, "Goodby"); /* write into lower corner */
dvid_putchr('!'); /* this char should be at 12, 40 */
SEE ALSO: dvid_say(), dvid_sayr(), dvid_char_at()
DV_CHAT.FNC - Thu 23 Nov 89 00:20 - Page 52:
NAME
dvid_char_at -- display character at specified position
PROTOTYPED IN: mflconio.h
SYNOPSIS
void dvid_char_at(row, col, ch);
int row, col; position to display
char *string; string to display
char ch; character to display
DESCRIPTION
This function uses the features of the MicroFirm Funtion Library's
display package functions, and must therefore follow the rules laid down
for their use. Specifically, dvid_init() must be called prior to using
this function, and the function may fail if the target system is not a
very close compatible since direct memory writing is being used.
dvid_char_at() passes only a carriage return, linefeed, backspace, tab,
and bell control code. All other control codes are ignored. Before
using this call, be sure the display package cursor position and the
screen position are equal by doing a dvid_flush() call. dvid_char_at()
performs the dvid_flush() call before returning, thereby insuring cursor
updating.
EXAMPLE
int i;
dvid_init(); /* initialize the package */
dvid_cls(); /* clear the screen */
dvid_say(0, 0, "Hello"); /* write to upper left corner */
for(i = 0; i < 10; i++) {
dvid_char_at(i, i+1, i | '0'); /* write a sequence */
}
dvid_move(12, 40); /* move to center of screen */
dvid_flush(); /* physically update screen cursor */
dvid_sayr(20, 70, "Goodby"); /* write into lower corner */
dvid_putchr('!'); /* this char should be at 12, 40 */
SEE ALSO: dvid_say(), dvid_sayr(), dvid_char_atr()
DV_CHATR.FNC - Thu 23 Nov 89 00:20 - Page 53:
NAME
dvid_chgattrib -- alter attribute in an area
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_chgattrib(srow, scol, erow, ecol, attrib);
int srow; starting row number
int scol; starting column number
int row; absolute row number
int ecol; ending column number
int attrib; video attribute
DESCRIPTION
The dvid_chgattrib() function may be used to alter the attributes on a
region of the screen starting at row (srow) and column (scol), up to and
including (erow) and (ecol), to the new (attribute). This provides a
means of changing the color of a region of the screen from 1 character
to the full screen without altering the character data in memory. The
direct video access functions are described in some detail in the users
manual accompanying the MicroFirm Function Library. They are only
briefly reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
DV_CLFLD.FNC - Thu 23 Nov 89 00:20 - Page 54:
NAME
dvid_clrfield -- clear a screen field
PROTOTYPED IN: mflconio.h
SYNOPSIS
void dvid_clrfield(row, col, size);
int row, col; starting point
int size; number of columns to clear ( <= 80)
int page; video page number
(for non-CGA, specify 0)
DESCRIPTION
This function handles the problem of clearing a section of a line on
the screen without clearing to the end of the line. dvid_clrfield()
will use the current screen attribute. The field is cleared to ASCII
spaces. If the size parameter is larger than 80, it is forced to 80.
EXAMPLE
dvid_clrfield(10, 20, 15, 0); /* clear 15 columns on page 0
starting at row 10, column 20 */
SEE ALSO: dvid_cls()
DV_CLS.FNC - Thu 23 Nov 89 00:20 - Page 55:
NAME
dvid_cls -- clear the display and home cursor
PROTOTYPED IN: mflconio.h
SYNOPSIS
void dvid_cls();
DESCRIPTION
This function uses the features of the MicroFirm Funtion Library's
display package functions, and must therefore follow the rules laid down
for their use. Specifically, dvid_init() must be called prior to using
this function, and the function may fail if the target system is not a
very close compatible since direct memory writing is being used.
dvid_cls() will clear the screen.
EXAMPLE
int i;
dvid_init(); /* initialize the package */
dvid_cls(); /* clear the screen */
dvid_say(0, 0, "Hello"); /* write to upper left corner */
for(i = 0; i < 10; i++) {
dvid_char_at(i, i+1, i | '0'); /* write a sequence */
}
dvid_move(12, 40); /* move to center of screen */
dvid_flush(); /* physically update screen cursor */
dvid_sayr(20, 70, "Goodby"); /* write into lower corner */
dvid_putchr('!'); /* this char should be at 12, 40 */
SEE ALSO: dvid_clrfield(), d_cls()
DV_DONE.FNC - Thu 23 Nov 89 00:20 - Page 56:
NAME
dvid_done -- de-initialize the functions
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_done(void);
DESCRIPTION
The dvid_done() function is called before exiting a program to restore
screen characteristics. It may also be used from within a program to
restore all default values within the direct video package. The direct
video access functions are described in some detail in the users manual
accompanying the MicroFirm Function Library. They are only briefly
reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
SEE ALSO: dvid_init()
DV_EEOL.FNC - Thu 23 Nov 89 00:20 - Page 57:
NAME
dvid_e2eol -- erase from cursor to end of line
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_e2eol(void);
DESCRIPTION
The dvid_e2eol() function is used to erase (to spaces) the screen from
the current internal cursor position to the end of the line e2eol. The
direct video access functions are described in some detail in the users
manual accompanying the MicroFirm Function Library. They are only
briefly reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
SEE ALSO: dvid_e2eos()
DV_EEOS.FNC - Thu 23 Nov 89 00:20 - Page 58:
NAME
dvid_e2eos -- erase cursor to end of screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_e2eos(void);
DESCRIPTION
The dvid_e2eos() function is used to erase (to spaces) the screen from
the current internal cursor position to the end of the current video
page. The direct video access functions are described in some detail in
the users manual accompanying the MicroFirm Function Library. They are
only briefly reviewed here. Be sure to look at the utility file
"dump.c" for examples of function usage.
SEE ALSO: dvid_e2eol()
DV_FLUSH.FNC - Thu 23 Nov 89 00:20 - Page 59:
NAME
dvid_flush -- update real cursor position
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_flush(void);
DESCRIPTION
The dvid_flush() function is called to force the onscreen cursor to the
position defined by the "internal" cursor position. During video
writes, an internal cursor position is maintained, but the onscreen
cursor is NOT automatically updated to reflect the current writing
position. This function resolves the discrepancy. The direct video
access functions are described in some detail in the users manual
accompanying the MicroFirm Function Library. They are only briefly
reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
SEE ALSO: dvid_move()
DV_GTATR.FNC - Thu 23 Nov 89 00:20 - Page 60:
NAME
dvid_getattr -- fetch the current attribute
PROTOTYPED IN: mflconio.h
SYNOPSIS
attrib = dvid_getattr(void);
int attrib; video attribute
DESCRIPTION
The dvid_getattr() function is used to return the current attribute used
for writing. It will return the value previously set with dvid_attrib().
The direct video access functions are described in some detail in the
users manual accompanying the MicroFirm Function Library. They are only
briefly reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
SEE ALSO: dvid_attrib()
DV_GTMOD.FNC - Thu 23 Nov 89 00:20 - Page 61:
NAME
dvid_getmode -- gets the current translation mode
PROTOTYPED IN: mflconio.h
SYNOPSIS
r = dvid_getmode();
int r; current translation mode (raw = TRUE)
DESCRIPTION
The dvid_getmode() function retrieves the current control character
translation mode. The direct video access functions are described in
some detail in the users manual accompanying the MicroFirm Function
Library. They are only briefly reviewed here. Be sure to look at the
utility file "dump.c" for examples of function usage.
SEE ALSO: dvid_raw()
DV_INIT.FNC - Thu 23 Nov 89 00:20 - Page 62:
NAME
dvid_init -- initialize the direct video functions
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_init(void);
DESCRIPTION
The dvid_init() function MUST be called before any other dvid* functions
are used. This function discovers the type of video card and mode in
use and sets internal variables accordingly. The direct video access
functions are described in some detail in the users manual accompanying
the MicroFirm Function Library. They are only briefly reviewed here.
Be sure to look at the utility file "dump.c" for examples of function
usage.
SEE ALSO: dvid_done()
DV_MOVE.FNC - Thu 23 Nov 89 00:20 - Page 63:
NAME
dvid_move -- set internal cursor position
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_move(row, col);
int row; absolute row number
int col; absolute column number
DESCRIPTION
The dvid_move() function sets the "internal" cursor to the specified
(row) and (col) positions. Subsequent writes to the screen will begin
at this position. The direct video access functions are described in
some detail in the users manual accompanying the MicroFirm Function
Library. They are only briefly reviewed here. Be sure to look at the
utility file "dump.c" for examples of function usage.
DV_NTERD.FNC - Thu 23 Nov 89 00:20 - Page 64:
NAME
dvid_enterdata -- enter a string of data from keyboard
PROTOTYPED IN: mflconio.h
SYNOPSIS
r = dvid_enterdata(dest, qty, row, col, mode);
int r; returns TRUE or FALSE
char *dest; destination for string
int qty; maximum allowable chars + 1
int row, col; row and column of string start*
int mode; mode for character checking
DESCRIPTION
This function provides a convenient method for entering character
strings from the keyboard and verifying the character syntax. Line
editing is supported to enhance user input. Entry is as follows:
Carriage Return terminates input and returns TRUE.
If no other data was entered, destination string
is NULLed in the first position. CR is not placed
into destination.
ESCape terminates entry at once, NULLs destination,
clears screen field, and returns FALSE.
HOME clears field, and restarts entry without returning.
BACKSPACE and Cursor Left will destructively backspace
up to beginning of field.
Only qty - 1 characters will be accepted.
Any error sounds console BELL.
Various modes allow for checking of syntax and mapping
of characters:
Mode 0: allow any printable character (ASCII 20H - 7FH)
Mode 1: allow only alphabetics (A-Z, a-z)
Mode 2: allow alphabetics and numerals only
Mode 3: allow numerials only
Mode 4: allow hexadecimal characters only (0-9, A-F, a-f)
Modes 0, 1, and 2 will map lower case to upper case if
decimal 128 (80H) is OR'd with the mode.
DV_NTERD.FNC - Thu 23 Nov 89 00:20 - Page 65:
EXAMPLE
char string[31];
unsigned int num;
d_pos(10, 20, 0); /* cursor to row 10, column 20 */
fputs("Enter an alphabetic string: ", stdout);
if(!dvid_enterdata(string, 31, 10, 48, 1)) {
fputs("\nESCape was pressed");
}
else printf("\nString entered is %s\n", string);
fputs("Enter hex value at current cursor position: ", stdout);
if(!dvid_enterdata(string, 5, -1, 0, 4)) {
fputs("\nESCape was pressed");
}
else {
num = atoi(string);
printf("Number entered was %4x", num);
}
SEE ALSO: dvid_enterfn(), enterdata()
DV_NTERF.FNC - Thu 23 Nov 89 00:20 - Page 66:
NAME
dvid_enterfn -- enter a filename from keyboard
PROTOTYPED IN: mflconio.h
SYNOPSIS
void dvid_enterfn(dest, qty, row, col, allow);
char *dest; destination for string
int qty; maximum allowable chars + 1
int row, col; row and column of string start*
int allow; TRUE to allow entension entry
DESCRIPTION
This function provides a convenient method for entering a path and
filename from the keyboard and verifying the character syntax. Line
editing is supported to enhance user input. Entry is as follows:
Carriage Return terminates input.
If no other data was entered, destination string
is NULLed in the first position. CR is not placed
into destination.
ESCape terminates entry at once, NULLs destination,
and clears screen field.
HOME clears field, and restarts entry without returning.
BACKSPACE and Cursor Left will destructively backspace
up to beginning of field.
Only qty - 1 characters will be accepted.
Any error sounds console BELL.
If "allow" is TRUE, then a filename extension may be
entered. Otherwise, no extension may be entered, since
the period character will be disallowed.
A drive may be specified; the colon is only allowed in the
second character string position.
EXAMPLE
char string[31];
d_pos(10, 20, 0); /* cursor to row 10, column 20 */
fputs("Enter a filename: ", stdout);
dvid_enterfn(string, 31, 10, 38, TRUE));
fputs("Enter filename at current cursor position: ", stdout);
dvid_enterfn(string, 31, -1, 0, FALSE);
SEE ALSO: dvid_enterdata(), enterfn()
DV_PRNTF.FNC - Thu 23 Nov 89 00:20 - Page 67:
NAME
dvid_printf -- write a formatted string to screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
r = dvid_printf(str, ...);
int r; number of characters written
char *str; format string
char ch; 8 bit character value
DESCRIPTION
The dvid_printf() function formats a string at the current internal
cursor position. This may not be the visible cursor position, since the
visible cursor is updated to the internal cursor only with the
dvid_flush() function. Its syntax is identical to the familiar library
printf() function. The direct video access functions are described in
some detail in the users manual accompanying the MicroFirm Function
Library. They are only briefly reviewed here. Be sure to look at the
utility file "dump.c" for examples of function usage.
SEE ALSO: dvid_printfa(), dvid_putstr()
DV_PRTFA.FNC - Thu 23 Nov 89 00:20 - Page 68:
NAME
dvid_printfa -- write formatted string to screen w/ attribute
PROTOTYPED IN: mflconio.h
SYNOPSIS
r = dvid_printfa(attrib, str, ...);
int r; number of characters written
int attrib; video attribute (color)
char *str; format string
char ch; 8 bit character value
DESCRIPTION
The dvid_printfa() function formats a string at the current internal
cursor position using the specified video attribute. This may not be
the visible cursor position, since the visible cursor is updated to the
internal cursor only with the dvid_flush() function. Its syntax is
identical to the familiar library printf() function. The direct video
access functions are described in some detail in the users manual
accompanying the MicroFirm Function Library. They are only briefly
reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
SEE ALSO: dvid_printfa(), dvid_putsa()
DV_PUTC.FNC - Thu 23 Nov 89 00:20 - Page 69:
NAME
dvid_putchr -- write a character to the screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_putchr(ch);
char ch; 8 bit character value
DESCRIPTION
The dvid_putchr() function is the real workhorse of the direct video
functions. It is this function which writes the specified (char) to the
screen memory with the current attribute at the current internal row/col
position. The direct video access functions are described in some
detail in the users manual accompanying the MicroFirm Function Library.
They are only briefly reviewed here. Be sure to look at the utility
file "dump.c" for examples of function usage.
SEE ALSO: dvid_putstr(), dvid_putsa()
DV_PUTS.FNC - Thu 23 Nov 89 00:20 - Page 70:
NAME
dvid_putstr -- write a string to screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_putstr(str);
char *str; character string
char ch; 8 bit character value
DESCRIPTION
The dvid_putstr() function places a string at the current internal
cursor position. This may not be the visible cursor position, since the
visible cursor is updated to the internal cursor only with the
dvid_flush() function. The direct video access functions are described
in some detail in the users manual accompanying the MicroFirm Function
Library. They are only briefly reviewed here. Be sure to look at the
utility file "dump.c" for examples of function usage.
SEE ALSO: dvid_putchr(), dvid_putsa()
DV_PUTSA.FNC - Thu 23 Nov 89 00:20 - Page 71:
NAME
dvid_putsa -- display a string with attribute
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_putsa(string,vattr);
char *string; string to display
int vattr; video attribute to use
DESCRIPTION
The dvid_putsa function works exactly the same as fputs and requires the
use of the display package (i.e. dvid_init must have previously been
called). The specified string is displayed in the specified attribute.
Any newline characters, embedded or trailing, will invoke a temporary
switch back to the old attribute, thus attribute bleeding when
scrolling.
EXAMPLE
dvid_putsa("This is\na test",YELLOW+(BLUE<<4),NORMAL);
SEE ALSO: dvid_init()
DV_RAW.FNC - Thu 23 Nov 89 00:20 - Page 72:
NAME
dvid_raw -- set display mode for control characters
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_raw(rawflag);
int rawflag; LOGICAL flag (TRUE or FALSE)
DESCRIPTION
The dvid_raw() function determines how characters between 00h and 1fh
will be treated. The display package defaults to a mode which treats
characters such as carriage return and bell as true control
characters, rather than values to be displayed. By calling this
function with an argument of TRUE, any of these characters will be
literally displayed, rather than interpreted as controls. Calling
divd_raw(FALSE) restores normal operation. Does not have any effect
if BIOS mode has been enabled. The direct video access functions are
described in some detail in the users manual accompanying the
MicroFirm Function Library. They are only briefly reviewed here. Be
sure to look at the utility file "dump.c" for examples of function
usage.
SEE ALSO: dvid_getmode()
DV_REP.FNC - Thu 23 Nov 89 00:20 - Page 73:
NAME
dvid_rep -- write a repeated character
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_rep(ch, count);
char ch; 8 bit character value
int count; number of chars to write or repeat
DESCRIPTION
The dvid_rep() function will place a given number of a repeated
character at the current internal cursor position. An alternate method
is to use dvid_setcount() followed by dvid_putchr(). The direct video
access functions are described in some detail in the users manual
accompanying the MicroFirm Function Library. They are only briefly
reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
SEE ALSO: dvid_setcount(), dvid_putchr()
DV_SAY.FNC - Thu 23 Nov 89 00:20 - Page 74:
NAME
dvid_say -- display a string at specified position
PROTOTYPED IN: mflconio.h
SYNOPSIS
void dvid_say(row, col, string);
int row, col; position to display
char *string; string to display
char ch; character to display
DESCRIPTION
This function uses the features of the MicroFirm Function Library's
display package functions, and must therefore follow the rules laid down
for their use. Specifically, dvid_init() must be called prior to using
this function, and the function may fail if the target system is not a
very close compatible since direct memory writing is being used.
dvid_say() writes a string at the current real cursor position and then
executes a dvid_flush() call before returning, thereby insuring cursor
updating.
EXAMPLE
int i;
dvid_init(); /* initialize the package */
dvid_cls(); /* clear the screen */
dvid_say(0, 0, "Hello"); /* write to upper left corner */
for(i = 0; i < 10; i++) {
dvid_char_at(i, i+1, i | '0'); /* write a sequence */
}
dvid_move(12, 40); /* move to center of screen */
dvid_flush(); /* physically update screen cursor */
dvid_sayr(20, 70, "Goodby"); /* write into lower corner */
dvid_putc('!'); /* this char should be at 12, 40 */
SEE ALSO: d_say(), dvid_sayr(), dvid_char_at(), dvid_char_atr()
DV_SAYR.FNC - Thu 23 Nov 89 00:20 - Page 75:
NAME
dvid_sayr -- dvid_say, returns cursor to starting point
PROTOTYPED IN: mflconio.h
SYNOPSIS
void dvid_sayr(row, col, string);
int row, col; position to display
char *string; string to display
char ch; character to display
DESCRIPTION
This function uses the features of the MicroFirm Function Library's
display package functions, and must therefore follow the rules laid down
for their use. Specifically, dvid_init() must be called prior to using
this function, and the function may fail if the target system is not a
very close compatible since direct memory writing is being used.
dvid_sayr() writes a string at the current real cursor position. Before
using this call, be sure the display package cursor position and the
screen position are equal by doing a dvid_flush() call.
EXAMPLE
int i;
dvid_init(); /* initialize the package */
dvid_cls(); /* clear the screen */
dvid_say(0, 0, "Hello"); /* write to upper left corner */
for(i = 0; i < 10; i++) {
dvid_char_at(i, i+1, i | '0'); /* write a sequence */
}
dvid_move(12, 40); /* move to center of screen */
dvid_flush(); /* physically update screen cursor */
dvid_sayr(20, 70, "Goodby"); /* write into lower corner */
dvid_putc('!'); /* this char should be at 12, 40 */
SEE ALSO: dvid_say(), d_say(), dvid_char_at(), dvid_char_atr()
DV_SCRL.FNC - Thu 23 Nov 89 00:20 - Page 76:
NAME
dvid_scroll -- scroll a region of the screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_scroll(lines, srow, scol, erow, ecol, attrib);
int lines; mode for region scroll
int srow; starting row number
int erow; ending row number
int scol; starting column number
int ecol; ending column number
int attribute; video attribute
DESCRIPTION
The dvid_scroll() function scrolls a region of the screen. If the first
argument is equal to 0 the region is cleared. If less than zero, the
region is scrolled down. If greater than zero, scrolled up. The direct
video access functions are described in some detail in the users manual
accompanying the MicroFirm Function Library. They are only briefly
reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
DV_SETCT.FNC - Thu 23 Nov 89 00:20 - Page 77:
NAME
dvid_setcount -- set number of chars to write
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_setcount(count);
int count; number of chars to write or repeat
DESCRIPTION
The dvid_setcount() function sets the number of times the NEXT character
displayed will be actually displayed. Always is automatically restored
to 1. The direct video access functions are described in some detail in
the users manual accompanying the MicroFirm Function Library. They are
only briefly reviewed here. Be sure to look at the utility file
"dump.c" for examples of function usage.
SEE ALSO: dvid_putchr()
DV_SETPG.FNC - Thu 23 Nov 89 00:20 - Page 78:
NAME
dvid_setpage -- set video page for writing, reading, and display
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_setpage(page, mode);
int page; video page number 0-7
int mode; LOGICAL flag (TRUE or FALSE)
DESCRIPTION
The dvid_setpage() function is used ONLY with CGA cards, which may
switch their video "pages". In 40 column modes, there are 8 pages
numbered 0-7. In 80 column modes, there are 4 pages, numbered 0-3.
Any page may be set for reading or writing, while setting a different
or the same page for actual display. The (page) argument specifies
the page number desired for writing, and is checked against the
current video mode for correctness. The (mode) argument is 0 to
select the page for writing/reading only, without changing the page
current specified for display. (mode) set to 1 also changes the
displayed page to the indicated (page). This function may therefore
be used to alter not only the destination for direct memory writes,
but also may be used to switch the display to the various pages. The
direct video access functions are described in some detail in the
users manual accompanying the MicroFirm Function Library. They are
only briefly reviewed here. Be sure to look at the utility file
"dump.c" for examples of function usage.
DV_SYNC.FNC - Thu 23 Nov 89 00:20 - Page 79:
NAME
dvid_sync -- enable or disable video sync
PROTOTYPED IN: mflconio.h
SYNOPSIS
dvid_sync(mode);
int mode; LOGICAL flag (TRUE or FALSE)
DESCRIPTION
The dvid_sync() function is used to control video synchronization on
CGA cards. Normally, the functions default to sync enabled to
prevent video "snow" during writes. (mode) may be set to FALSE to
disable video sync. On some color cards, no snow will result evem
without sync. For all cards, disabling sync will speed up access,
although the resulting "snow" may be objectionable. N.B.: Often,
there will be a little snow on the left edge of the screen, even with
video sync enabled. Turning off the visible cursor using
cursor_style() in this library can often eliminate the snow, which is
actually caused by the cursor itself. The direct video access
functions are described in some detail in the users manual
accompanying the MicroFirm Function Library. They are only briefly
reviewed here. Be sure to look at the utility file "dump.c" for
examples of function usage.
ENTERDAT.FNC - Thu 23 Nov 89 00:20 - Page 80:
NAME
enterdata -- enter a string of data from keyboard
PROTOTYPED IN: mflconio.h
SYNOPSIS
r = enterdata(dest, qty, row, col, mode);
int r; returns TRUE or FALSE
char *dest; destination for string
int qty; maximum allowable chars + 1
int row, col; row and column of string start*
int mode; mode for character checking
DESCRIPTION
enterdata() provides a convenient method for entering character
strings from the keyboard and verifying the character syntax. Line
editing is supported to enhance user input. Entry is as follows:
Carriage Return terminates input and returns TRUE. If no other
data was entered, destination string is NULLed in the
first position. CR is not placed into destination.
ESCape terminates entry at once, NULLs destination, clears
screen field, and returns FALSE.
HOME clears field, and restarts entry without returning.
BACKSPACE and Cursor Left will destructively backspace up
to beginning of field.
Only qty - 1 characters will be accepted.
Any error sounds console BELL.
Various modes allow for checking of syntax and mapping of characters
:
Mode 0: allow any printable character (ASCII 20H - 7FH)
Mode 1: allow only alphabetics (A-Z, a-z)
Mode 2: allow alphabetics and numerals only
Mode 3: allow numerials only Mode 4: allow hexadecimal
characters only (0-9, A-F, a-f) Modes 0, 1, and 2 will map
lower case to upper case if decimal 128 (80H) is OR'd with
the mode.
* If row = -1, then current cursor position will be used, and col value i
s ignored.
ENTERDAT.FNC - Thu 23 Nov 89 00:20 - Page 81:
EXAMPLE
char string[31];
unsigned int num;
d_pos(10, 20, 0); /* cursor to row 10, column 20 */
fputs("Enter an alphabetic string: ", stdout);
if(!enterdata(string, 31, 10, 48, 1)) {
fputs("\nESCape was pressed");
}
else printf("\nString entered is %s\n", string);
fputs("Enter hex value at current cursor position: ", stdout);
if(!enterdata(string, 5, -1, 0, 4)) {
fputs("\nESCape was pressed");
}
else {
num = atoi(string);
printf("Number entered was %4x", num);
}
SEE ALSO: disp_enterdata()
ENTERFN.FNC - Thu 23 Nov 89 00:20 - Page 82:
NAME
enterfn -- enter a filename from keyboard
PROTOTYPED IN: mflconio.h
SYNOPSIS
void enterfn(dest, qty, row, col, allow);
char *dest; destination for string
int qty; maximum allowable chars + 1
int row, col; row and column of string start*
int allow; TRUE to allow entension entry
DESCRIPTION
enterfn() provides a convenient method for entering a path and
filename from the keyboard and verifying the character syntax. Line
editing is supported to enhance user input. Entry is as follows:
Carriage Return terminates input.
If no other data was entered, destination string
is NULLed in the first position. CR is not placed
into destination.
ESCape terminates entry at once, NULLs destination,
and clears screen field.
HOME clears field, and restarts entry without returning.
BACKSPACE and Cursor Left will destructively backspace
up to beginning of field.
Only qty - 1 characters will be accepted.
Any error sounds console BELL.
If "allow" is TRUE, then a filename extension may be
entered. Otherwise, no extension may be entered, since
the period character will be disallowed.
A drive may be specified; the colon is only allowed in the
second character string position.
EXAMPLE
char string[31];
d_pos(10, 20, 0); /* cursor to row 10, column 20 */
fputs("Enter a filename: ", stdout);
enterfn(string, 31, 10, 38, TRUE));
fputs("Enter filename at current cursor position: ", stdout);
enterfn(string, 31, -1, 0, FALSE);
* If row = -1, then current cursor position will be used, and
col value is ignored.
SEE ALSO: disp_enterfn()
ERAOK.FNC - Thu 23 Nov 89 00:20 - Page 83:
NAME
eraok -- ask permission before overwriting existing file
PROTOTYPED IN: mflfiles.h
SYNOPSIS
void eraok(filename);
char *filename filename to test
DESCRIPTION
This function checks for the existance of the specified filename
and if it exists, will ask the user (through stderr) if the file
can be lost. If the user responds Y or y, the file is lost and
return is made to the caller. If the response is anything else,
the program aborts immediately, and the routine does NOT return
to the caller. Exit is via the aabort() function of this library.
EXAMPLE
(assume argv[1] is string "foobar.com")
eraok(argv[1]);
printf("File %s has been deleted", argv[1]);
ERROR.FNC - Thu 23 Nov 89 00:20 - Page 84:
NAME
error -- report a fatal error and exit
PROTOTYPED IN: mflsys.h
SYNOPSIS
void error(string);
char *string; error message to report
DESCRIPTION
This function sends the specified error message to stderr, and
then exits through this library's aabort() function, sounding
the console bell on its way out.
EXAMPLE
error("Invalid syntax");
SEE ALSO: aabort()
EXISTS.FNC - Thu 23 Nov 89 00:20 - Page 85:
NAME
exists -- see if a file exists
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = exists(name);
int r; returns FALSE if not found, else TRUE
char *name; filename to check
DESCRIPTION
If the specified filename, which may include drive and
directory, is not found, then a value of zero (FALSE)
is returned. Else, one (TRUE) is returned. This
test does not take into consideration any attributes on
the file, so that an fopen() call may still fail later.
EXAMPLE
if(exists("a:foo.bar")) puts("File exists!");
else puts("File does not exist");
SEE ALSO: access()
EXIT2DOS.FNC - Thu 23 Nov 89 00:20 - Page 86:
NAME
exit2dos -- permission to exit program
PROTOTYPED IN: mflfiles.h
SYNOPSIS
void exit2dos();
DESCRIPTION
When invoked, this function clears the screen and places
the message "Exit to DOS?" in the center of the display.
The keyboard is read, and if the response is 'Y' or 'y',
an aabort(0) function is called. For any other response,
the function simply returns to the users program, which
must then do whatever is necessary to continue with the
program.
EXAMPLE
if(getche() == ESC) exit2dos(); /* watch for ESCape key */
else domorework();
EXPARG.FNC - Thu 23 Nov 89 00:20 - Page 87:
NAME
expand_arg -- expand command line wildcard filenames
PROTOTYPED IN: mflfiles.h
SYNOPSIS
nargc = expand_arg(argc, argv);
int nargc; no. of arguments in nargv
int argc; no. of original arguments
char *argv[]; original argument array
extern char **nargv; expanded argument array
DESCRIPTION
The expand_arg() function is similar to UNIX exarg processing to expand
wildcard filenames. This makes wildcard expansion totally transparent
to the programmer. Most implementations of C compilers for MS-DOS don't
provide this expansion. Therefore, if one command line argument is
"*.ASM", this becomes one of the arguments to a program, instead of all
files which will match the expansion. expand_arg() will take the (argc,
argv) passed through the main() function, and make a new array, called
(nargc, nargv) which will contain the expanded parameters. If there are
no wildcards to expand, the new array winds up being the same as the old
array. In addition, certain arguments will not be expanded, as they
will be considered possible "options" or "literals". Any argument
beginning with a hyphen (-), fraction bar (/), or single/double quote ("
') will not be expanded. Arguments beginning with a reverse slash (\)
will be assumed to contain a directory name as part of a potential
filename. Arguments will be expanded if they contain either of the
wildcard characters (*) or (?). No matches to the specification will
return no filenames. A filename without a wildcard designator will be
passed to the new array without testing for existence. Filenames
expanded will, of course, exist, or they wouldn't have been found.
The label "nargc" is not a mandatory label. It is chosen merely for
convenience in designating the new argument count. However, the array
name "nargv" is a requirement, since the object module expand_arg
defines that item. If you use the file "smdefs.h", the external
reference to nargv will be done automatically, and you needn't worry
about it.
EXPARG.FNC - Thu 23 Nov 89 00:20 - Page 88:
The expand_arg() function does dynamic memory allocation and re-
allocation, and therefore should be called as the FIRST function after
main(), and NEVER called again within the program. Violation of this
requirement may cause some arguments to be lost if this function has to
reallocate memory during expansion. Since wildcard expansion may result
in more or less arguments than originally passed, nargc will seldom
equal argc. It may be either larger or smaller.
After calling expand_arg(), the variables nargc and nargv may be used
anywhere you would normally have used argc and argv. If expand_arg()
fails (usually a memory allocatiion problem), it will return a value of
0. No command line options would return 1, since the program name
itself is a command line argument.
EXAMPLE
#include <stdio.h>
#include <mflfiles.h>
int nargc;
main(int argc, char *argv[])
{
int i;
nargc = expand_arg(argc, argv);
if(nargc == 0)
error("Memory allocation error");
for(i = 0; i < nargc; i++)
printf("Argument %d is %s\n", i, nargv[i]);
}
SEE ALSO: Demo WC.C
EXTTYP.FNC - Thu 23 Nov 89 00:20 - Page 89:
NAME
exttyp -- check a filename for a particular extension
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = exttyp(filename, extn);
int r; returns TRUE if match, else FALSE
char *filename filename to test
char *extn extension string for match
DESCRIPTION
This function makes no changes to either entry parameter,
but simply returns TRUE if the specified extension is found in
the filename, or FALSE (0) if it is not. Case of the characters is
ignored. The function is most useful to insure that a particular
program will only use an extension of a specified type.
EXAMPLE
(assume argv[1] is string "foobar.com")
if(exttyp(argv[1], "COM")) printf("File is executable");
else printf("File is not executable");
FCBCLOSE.FNC - Thu 23 Nov 89 00:20 - Page 90:
NAME
FCB_close -- close a file using a file control block
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = FCB_close(f);
int r; SUCCESS or ERROR
struct xfcb *f; pointer to opened FCB to close
DESCRIPTION
With the advent of DOS 2.0, the File Control Block (FCB) method of
file handling was superceded by the use of file handles. Even
though rarely used, DOS retains the ability to process the older
style FCB calls. This is normally of little interest except that
there are still two functions which cannot be performed any way
except by the use of FCBs.
DOS has no provisions for creating or deleting a volume label
using file handles. FCB_creat() will allow any type of file, even
volume labels, to be created. Note that the file name may not
contain any path information since DOS 1.0 (and CP/M before it)
did not support nested subdirectories. You must therefore be in
the same directory where the file is to be created. See pushdir()
and popdir() for a convenient way to relocate to a directory where
an FCB operation is to be performed.
FCB_close() closes a previously opened FCB and deallocates its
memory.
EXAMPLE
char buf[128];
struct XFCB my_fcb;
if (NULL != (my_fcb=FCB_open("fname.tmp", -1))) {
FCB_reads(my_fcb,buf); /* read the 1st record */
FCB_readr(my_fcb,buf,7L); /* read the 7th record */
FCB_writes(my_fcb,buf); /* write the 8th record */
FCB_writer(my_fcb,buf,4L); /* write the 4th record */
}
FCB_close(my_fcb);
SEE ALSO: FCB_creat(), FCB_kill(), FCB_open()
FCBCREAT.FNC - Thu 23 Nov 89 00:20 - Page 91:
NAME
FCB_creat -- create a file using a file control block
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = FCB_creat(fname,attrib);
int r; returns 0 if success, else ERROR
char *fname; name of the file to create
int attrib; attribute of the file to create
DESCRIPTION
With the advent of DOS 2.0, the File Control Block (FCB) method of
file handling was superceded by the use of file handles. Even though
rarely used, DOS retains the ability to process the older style FCB
calls. This is normally of little interest except that there are still
two functions which cannot be performed any way except by the use of
FCBs.
DOS has no provisions for creating or deleting a volume label using
file handles. FCB_creat() will allow any type of file, even volume
labels, to be created. Note that the file name may not contain any
path information since DOS 1.0 (and CP/M before it) did not support
nested subdirectories. You must therefore be in the same directory
where the file is to be created. See pushdir() and popdir() for a
convenient way to relocate to a directory where an FCB operation is to
be performed.
EXAMPLE
struct FIND *ffblk;
char *p;
pushdir("C:\\"); /* go to the C: root directory */
/* next look for an old volume label to delete, but be */
/* aware that its filename may have to be fixed */
if (NULL != (ffblk = findfirst("*.*", FA_LABEL))) do {
if (fflbk->attribute & FA_LABEL)
break;
} while (NULL != (ffblk = findnext()));
if (ffblk) {
if ('.' == ffblk->name[8]) /* not in a volume label */
strcpy(&ffblk->name[8], &ffblk->name[9]);
FCB_kill(ffblk->name, FA_LABEL);
}
/* create a new volume label */
FCB_creat("A NEW LABEL", FA_LABEL);
if (!chdir("PIRATED")) /* go to a subdirectory */
FCB_kill("*.*", 0); /* quickly wipe out all files */
popdir(); /* go back where we were */
SEE ALSO: FCB_kill(), FCB_open(), FCB_close()
FCBKILL.FNC - Thu 23 Nov 89 00:20 - Page 92:
NAME
FCB_kill -- delete a file using a file control block
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = FCB_kill(fname,attrib);
int r; returns 0 if success, else ERROR
char *fname; name of the file to delete
int attrib; attribute of the file to delete
DESCRIPTION
With the advent of DOS 2.0, the File Control Block (FCB) method of
file handling was superceded by the use of file handles. Even though
rarely used, DOS retains the ability to process the older style FCB
calls. This is normally of little interest except that there are still
two functions which cannot be performed any way except by the use of
FCBs.
FCB_kill() is capable of deleting volume labels, which no other DOS
function can do. Perhaps even more useful is it's capability to delete
multiple wildcard-specified files. This is how DOS's own DEL and ERASE
commands can delete entire groups of files so much more quickly than
by using findfirst()/findnext() and unlink().
One note on the kill and create functions - You will notice than
FCB_kill also requires an attribute parameter be passed to it. The
reason for this is because volume labels break all the DOS rules
for file naming. Both FCB_creat() and FCB_kill process file names
quite differently when the file is known to be a volume label -
which may contain spaces, and other characters illegal in DOS
filenames.
EXAMPLE
struct FIND *ffblk;
char *p;
pushdir("C:\\"); /* go to the C: root directory */
/* next look for an old volume label to delete, but be */
/* aware that its filename may have to be fixed */
if (NULL != (ffblk = findfirst("*.*", FA_LABEL))) do {
if (fflbk->attribute & FA_LABEL)
break;
} while (NULL != (ffblk = findnext()));
if (ffblk) {
if ('.' == ffblk->name[8]) /* not in a volume label */
strcpy(&ffblk->name[8], &ffblk->name[9]);
FCB_kill(ffblk->name, FA_LABEL);
}
SEE ALSO: FCB_creat(), FCB_open(), FCB_close()
FCBREADR.FNC - Thu 23 Nov 89 00:20 - Page 93:
NAME
FCB_readr -- random read using a file control block
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = FCB_readr(f,buf,rec);
int r; SUCCESS or ERROR
struct xfcb *f; pointer to opened FCB
char *buf; buffer to receive the data
long rec; record number to read
DESCRIPTION
With the advent of DOS 2.0, the File Control Block (FCB) method of
file handling was superceded by the use of file handles. Even though
rarely used, DOS retains the ability to process the older style FCB
calls. This is normally of little interest except that there are still
two functions which cannot be performed any way except by the use of
FCBs.
FCB_readr() reads data from a previously opened file using FCBs. data
are read as records of watever size was specified (if any - default is
128-byte records) in the the call to FCB_open(). FCB_readr() reads
random records as specified in the calling parameters.
EXAMPLE
char buf[128];
struct XFCB my_fcb;
if (NULL != (my_fcb=FCB_open("fname.tmp", -1)))
{
FCB_reads(my_fcb,buf); /* read the 1st record */
FCB_readr(my_fcb,buf,7L); /* read the 7th record */
FCB_writes(my_fcb,buf); /* write the 8th record */
FCB_writer(my_fcb,buf,4L); /* write the 4th record */
}
FCB_close(my_fcb);
SEE ALSO: FCB_creat(), FCB_kill(), FCB_open(), FCB_close(), FCB_reads(),
FCB_writes(), FCB_writer()
FCBREADS.FNC - Thu 23 Nov 89 00:20 - Page 94:
NAME
FCB_reads -- sequential read using a file control block
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = FCB_reads(f,buf);
int r; SUCCESS or ERROR
struct xfcb *f; pointer to opened FCB
char *buf; buffer to receive the data
DESCRIPTION
With the advent of DOS 2.0, the File Control Block (FCB) method of
file handling was superceded by the use of file handles. Even though
rarely used, DOS retains the ability to process the older style FCB
calls. This is normally of little interest except that there are still
two functions which cannot be performed any way except by the use of
FCBs.
FCB_reads() reads data from a previously opened file using FCBs. Data
are read as records of watever size was specified (if any - default is
128-byte records) in the the call to FCB_open(). FCB_reads() reads
records sequentially.
EXAMPLE
char buf[128];
struct XFCB my_fcb;
if (NULL != (my_fcb=FCB_open("fname.tmp", -1)))
{
FCB_reads(my_fcb,buf); /* read the 1st record */
FCB_readr(my_fcb,buf,7L); /* read the 7th record */
FCB_writes(my_fcb,buf); /* write the 8th record */
FCB_writer(my_fcb,buf,4L); /* write the 4th record */
}
FCB_close(my_fcb);
SEE ALSO: FCB_creat(), FCB_kill(), FCB_open(), FCB_close(), FCB_readr(),
FCB_writes(), FCB_writer()
FCBWRITR.FNC - Thu 23 Nov 89 00:20 - Page 95:
NAME
FCB_writer -- random write using a file control block
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = FCB_writer(f,buf,rec);
int r; SUCCESS or ERROR
struct xfcb *f; pointer to opened FCB
char *buf; buffer containing the data to write
long rec; record number to write
DESCRIPTION
With the advent of DOS 2.0, the File Control Block (FCB) method of
file handling was superceded by the use of file handles. Even
though rarely used, DOS retains the ability to process the older
style FCB calls. This is normally of little interest except that
there are still two functions which cannot be performed any way
except by the use of FCBs.
FCB_writer() writes data to a previously opened file using FCBs. Data
are written as records of watever size was specified (if any - default
is 128-byte records) in the the call to FCB_open(). FCB_writer()
writes random records as specified in the calling parameters.
EXAMPLE
char buf[128];
struct XFCB my_fcb;
if (NULL != (my_fcb=FCB_open("fname.tmp", -1)))
{
FCB_reads(my_fcb,buf); /* read the 1st record */
FCB_readr(my_fcb,buf,7L); /* read the 7th record */
FCB_writes(my_fcb,buf); /* write the 8th record */
FCB_writer(my_fcb,buf,4L); /* write the 4th record */
}
FCB_close(my_fcb);
SEE ALSO: FCB_creat(), FCB_kill(), FCB_open(), FCB_close() FCB_reads(),
FCB_readr(), FCB_writes()
FCBWRITS.FNC - Thu 23 Nov 89 00:20 - Page 96:
NAME
FCB_writes -- sequential write using a file control block
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = FCB_writes(f,buf);
int r; SUCCESS or ERROR
struct xfcb *f; pointer to opened FCB
char *buf; buffer containing the data to write
DESCRIPTION
With the advent of DOS 2.0, the File Control Block (FCB) method of
file handling was superceded by the use of file handles. Even
though rarely used, DOS retains the ability to process the older
style FCB calls. This is normally of little interest except that
there are still two functions which cannot be performed any way
except by the use of FCBs.
FCB_writes() writes data to a previously opened file using FCBs. Data
are written as records of watever size was specified (if any - default
is 128-byte records) in the the call to FCB_open(). FCB_writes()
writes records sequentially.
EXAMPLE
char buf[128];
struct XFCB my_fcb;
if (NULL != (my_fcb=FCB_open("fname.tmp", -1)))
{
FCB_reads(my_fcb,buf); /* read the 1st record */
FCB_readr(my_fcb,buf,7L); /* read the 7th record */
FCB_writes(my_fcb,buf); /* write the 8th record */
FCB_writer(my_fcb,buf,4L); /* write the 4th record */
}
FCB_close(my_fcb);
SEE ALSO: FCB_creat(), FCB_kill(), FCB_open(), FCB_close(), FCB_reads(),
FCB_readr(), FCB_writer()
FCOPY.FNC - Thu 23 Nov 89 00:20 - Page 97:
NAME
fcopy -- copy a file
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = fcopy(from,to,over);
int r; SUCCESS if file successfully copied, else ERROR
char *from; file to copy
char *to; destination of copy operation - may be a file name
or a directory
int over; overwrite permission, TRUE or FALSE
DESCRIPTION
The fcopy() function copies files just like the DOS COPY command. It also
suffers some of the same limitations, e.g. the inability to overwrite
protected files. It adds the extra security feature of requiring
permission to overwrite an existing file.
EXAMPLE
char *file="FILE.EXT", *dest1="NEW_NAME.$$$", *dest2="NEW_DIR";
if (SUCCESS != fcopy(file,dest1,FALSE))
{ printf("Can't copy %s to %s\n", file, dest1);
if (SUCCESS == fcopy(file,dest1,TRUE))
puts("It already existed, but it's history now");
}
if (SUCCESS != fcopy(file,dest2,FALSE))
printf("Can't copy %s to directory %s\n", file, dest2);
SEE ALSO: rename()
FCRYPT.FNC - Thu 23 Nov 89 00:20 - Page 98:
NAME
crypt_install -- install a stream encryption filter
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = crypt_install(stream,key,lvl);
int r; SUCCESS or ERROR
SFILE *stream; stream to be filtered
char *key; encryption/decryption key
int lvl; zero for equivalence with crypt(), else the number
of unique characters (1-26) required in the key
DESCRIPTION
The crypt_install() function is a special-purpose stream filter which
allows data being read from or written to a stream to be encypted or
decrypted "on the fly" transparently to the user. The sfinstall() function
is called internally by crypt_install().
EXAMPLE
SFILE *infile;
infile = sfopen("file.ext", "r"); /* input from a file */
crypt_install(infile, "keytxt", 0); /* encrypt using "keytxt" */
sfinstall(infile, ucase_filt); /* after converting to UC */
SEE ALSO: crypt(), cryptqual(), sfopen(), scopen(), sclose(),
sfinstall(), ucase_filt, lcase_filt
FILLCH.FNC - Thu 23 Nov 89 00:20 - Page 99:
NAME
fillch -- fill a string with a character
PROTOTYPED IN: mflstrng.h
SYNOPSIS
void fillch(dest, chr, qty);
char *dest destination string
char chr character to place
int qty number to place
DESCRIPTION
This function fills string "dest" with "qty" number of characters
"chr". The destination string must be large enough to hold the
indicated quantity, as no check is made. In addition, a NULL
is not placed after the last character.
EXAMPLE
char string[20];
fillch(string, 'A', 19);
string[20] = NULL;
makes a usable string of 19 "A" characters.
FLN_FIX.FNC - Thu 23 Nov 89 00:20 - Page 100:
NAME
fln_fix -- remove "dot" directories from pathnames
PROTOTYPED IN: mflfiles.h
SYNOPSIS
path = fln_fix(path);
char *path; pathname to "scrunch"
DESCRIPTION
fln_fix() is called internally by flnorm() and can be used alone
though it is a somewhat dumber, yet still useful function than
flnorm(). Simply, fln_fix(), when passed a filename, ignores the drive
designation (i.e. "D:") and returns the same pathname, processed in
place, with all "dot" directories scrunched out. Note that fln_fix()
has no error return condition and always tries to fix whatever
filename it's passed. Basically, fln_fix() does the following:
1. Ignores all leading drive specs including network specs where
the colon (":") may not be the second character.
2. Calls unix2dos() to convert Unix-style filenames (i.e. using
the "/" character as a path separator) to DOS-style.
3. Leading backslashes, indicating the root directory are ignored.
If the root directory is specified, parent directory (double-
dot - "..") subdirectories are ignored.
4. Any doubled backslashes are converted to single backslashes.
5. Single dot (".") directories are scrunched.
6. Embedded double-dot directories are scrunched to remove the
preceding redundant level.
7. Trailing backslashes are preserved.
Also internally, the flnorm() function calls unix2dos() which
simply converts Unix-style path names (using '/' as the path
separator) to DOS-style (using '\' as the path separator).
EXAMPLE
char norml[MAX_FLEN]; /* defined in MFLDEFS.H */
if(flnorm(".\\..\\xyz\\..\\abc\\pdq",char_norml) {
puts("unable to normalize filename");
/* NOTE: even if pdq doesn't exist, if the rest of the
path can be normalized, "\PDQ" will be
appended and no error will be returned */
if(flnorm(".\\..\\xyz\\..\\abc\\pdq\\",char_norml) {
puts("bad path or not a directory");
puts(fln_fix("abc/123.4:/stuff/../.././junk/./garbage");
/* Prints "abc/123.4:\JUNK\GARBAGE" */
puts(unix2dos("unix_dos/style/path/name.ext"));
/* Prints "UNIX_DOS\STYLE\PATH\NAME.EXT" */
SEE ALSO: flnorm(), unix2dos()
FLNORM.FNC - Thu 23 Nov 89 00:20 - Page 101:
NAME
flnorm -- normalize a filename
PROTOTYPED IN: mflfiles.h
PORTABILITY: flnorm() is similar to functions included in many
standard libraries as well as many 3rd party libraries.
Many of thes functions, however, rely on DOS calls
introduced with DOS 3.0 and will therefore not work on
systems running DOS 2.xx.
SYNOPSIS
r = flnorm(path,norml);
int r; returns zero if valid, else ERROR
char *path; pathname to normalize
char *norml; buffer to receive normalized name
DESCRIPTION
DOS allows filenames and pathnames to be specified in a bewildering
variety of ways. Drive letters are optional, the two types of "dot"
directories may be freely interspersed in the name, and the path may
either be referenced to the current directory or the root. The primary
function of flnorm() is to determine if a file MAY exist. The drive
and path (if present) are validated to see if the named file may be
created or opened. As a secondary function, path names passed to
flnorm() with a trailing path delimiter ('\' or '/') are further
validated to verify that they exist and are directories.
Specifically, flnorm() "normalizes" file/path names according to the
following rules:
1. Filenames are first checked to see if they exist.
2. If a drive is specified, drvalid() is called to
verify it.
3. If the filename doesn't exist, but is on a valid drive,
the pathname is extracted and it is checked.
4. If the pathname is valid, it is normalized and the
file name reattached.
5. If the specified filename ends in a "\", it is assumed to
be a directory. If a file of the specified name is found,
an error is returned.
6. If nothing in the filename may be verified, an error
status is returned and the return filename is blanked.
The normalized filename is always of the form "D:\PATH\FILE"
even if "FILE" is specified as and found to be a directory.
A dangling "\" is only returned for the root directory.
FLNORM.FNC - Thu 23 Nov 89 00:20 - Page 102:
EXAMPLE
char norml[MAX_FLEN]; /* defined in MFLDEFS.H */
if(flnorm(".\\..\\xyz\\..\\abc\\pdq",char_norml) {
puts("unable to normalize filename");
/* NOTE: even if pdq doesn't exist, if the rest of the
path can be normalized, "\PDQ" will be
appended and no error will be returned */
if(flnorm(".\\..\\xyz\\..\\abc\\pdq\\",char_norml) {
puts("bad path or not a directory");
SEE ALSO: fln_fix, unix2dos
FLREMVOL.FNC - Thu 23 Nov 89 00:20 - Page 103:
NAME
flremvol -- removes the volume label on a specified disk drive
PROTOTYPED IN: mflfiles.h
PORTABILITY: Compatible with Blaise (tm) library functions of the same
name.
SYNOPSIS
r = flremvol(drv);
int r; SUCCESS or ERROR
char drv; the drive letter (A-Z, a-z) whose volume label to
remove
DESCRIPTION
The flremvol() function removes the volume label from any valid disk drive.
EXAMPLE
if (ERROR == flremvol('C'))
puts("cant remove volume label from drive C:");
SEE ALSO: flretvol(), flsetvol()
FLRETVOL.FNC - Thu 23 Nov 89 00:20 - Page 104:
NAME
flretvol -- get the volume label for a disk drive
PROTOTYPED IN: mflfiles.h
PORTABILITY: Compatible with Blaise (tm) library functions of the same
name.
SYNOPSIS
r = flretvol(drv);
char *r; the volume label or NULL if no label or an error
char drv; the drive letter to check (A-Z, a-z)
DESCRIPTION
The flretvol() function retrieves the volume label for any valid disk
drive. The returned volume label will be an ASCIIZ string, 1-11 characters
long, uppercase, and without the usual filename period between the 8th and
9th characters.
EXAMPLE
char *vlbl;
if (NULL == (vlbl = flretvol('C')))
puts("cant retrieve volume label from drive C:");
else printf("volume label of C: is %s\n", vlbl);
SEE ALSO: flremvol(), flsetvol()
FLSETVOL.FNC - Thu 23 Nov 89 00:20 - Page 105:
NAME
flsetvol -- sets the volume label on a specified disk drive
PROTOTYPED IN: mflfiles.h
PORTABILITY: Compatible with Blaise (tm) library functions of the same
name.
SYNOPSIS
r = flsetvol(drv,vlbl);
int r; SUCCESS or ERROR
char drv; the drive letter (A-Z, a-z) whose volume label to
set
char *vlbl; new volume label to set
DESCRIPTION
The flsetvol() function set the volume label on any valid disk drive. If a
volume label already exists for that drive, it is deleted. The specified
label may be upper or lower case, but will be converted to upper case by
DOS.
EXAMPLE
if (ERROR == flsetvol('C',"new_label"))
puts("cant set volume label on drive C:");
SEE ALSO: flretvol(), flremvol()
FNMERGE.FNC - Thu 23 Nov 89 00:20 - Page 106:
NAME
fnmerge -- merge drive/path/file/ext into a file string
PROTOTYPED IN: mflfiles.h
PORTABILITY: fnmerge() is a superset of a function of the same name
available in and TC
SYNOPSIS
void fnmerge(s1,s2,s3,s4,s5,s6,s7);
char *s1; buffer for file string
char *s2; drive
char *s3; drive+path
char *s4; path
char *s5; name+ext
char *s6; name
char *s7; ext
DESCRIPTION
The fnmerge() function takes the same sort of arguments as
fnsplit() and merges them to create a file name string. Note that
not all inputs are required. For example, if the drive+path is
given, the individual drive and path specs are ignored. This
assures compatibility with basename(). If the name+ext spec is
given, the individual name and extension specs are ignored.
If a path is give, either individually or included with a drive
spec, and does not include a terminating '\', one is appended. If
a separate extension spec is given, it may include a leading '.'
or not - one will be added if not. Finally, fnmerge() calls
unix2dos() to convert all embedded '/'s into '\'s. As with fnsplit,
other compiler implementations may be mimicked with macros.
EXAMPLE
char file[MAX_FLEN];
char *pname = "c:/use/this";
char *drive = "z:";
char *path = "not/this/";
char *fname = NULL; /* or = ""; */
char *name = "name";
char *ext = "ext"; /* leading '.' is optional */
fnmerge(file,drive,pname,path,fname,name,ext);
after execution file is "C:\USE\THIS\NAME.EXT"
SEE ALSO: basename(), fnsplit()
FNSPLIT.FNC - Thu 23 Nov 89 00:20 - Page 107:
NAME
fnsplit -- split a string into drive/path/file/ext
PROTOTYPED IN: mflfiles.h
PORTABILITY: fnsplit() is a superset of a function of the same name
available in and TC
SYNOPSIS
r=fnsplit(s1,s2,s3,s4,s5,s6,s7);
int r; bit map of file string features
bit 0 - Extension was specified
bit 1 - Filename was specified
bit 2 - Directory was specified
bit 3 - Drive was specified
bit 4 - Wildcards were specified in filename
bit 5 - Wildcards were specified in path
char *s1; original string
char *s2; destination for drive
char *s3; destination for drive+path
char *s4; destination for path
char *s5; destination for name+ext
char *s6; destination for name
char *s7; destination for ext
DESCRIPTION
The fnsplit() function requires more setup effort than basename() but
returns more information. In addition to ALL of the information
returned by basename(), fnsplit() also returns the drive
specification and separates the filename into name and extension
components. As with basename(), if any component isn't specified, an
empty string (i.e. first character = '\0') is returned for that
component. As a side effect, fnsplit() calls unix2dos() which
converts all '/' characters to '\' characters. A NULL passed for any
argument will be ignored, allowing simple macro emulation of other
compilers' implementations of fnsplit().
Internally, fnsplit() calls has_wild() which checks for the
existence of DOS wildcard characters ('*' and '?') in the path and
filename portions of the given string.
FNSPLIT.FNC - Thu 23 Nov 89 00:20 - Page 108:
EXAMPLE
char *name[] = "C:\looney\bin\wumpus.com";
char path[MAX_FLEN], file[13];
char drive[3], pname[MAX_FLEN], fname[9], ext[4];
fnsplit(name, drive, pname, path, file, fname, ext);
after execution, fnsplit returns 0x0f, arrays are as follows:
name (unchanged except '/'s converted to '\'s)
drive C:
pname C:\looney\bin\
path \looney\bin\
file wumpus.com
fname wumpus
ext .com
SEE ALSO: basename(), fnmerge(), has_wild()
FOPEND.FNC - Thu 23 Nov 89 00:20 - Page 109:
NAME
fopend -- fopen a file in an environment variable
PROTOTYPED IN: mflfiles.h
SYNOPSIS
fd = fopend(name, mode, envar);
FILE *fd;
char *name; filename
char *mode; mode
char *envar; name of environment variable
DESCRIPTION
This function allows the opening of a file in other than just the
current directory. It will attempt to do the open in the current
directory first, and if that fails, will then expand to search
according to a a specified environment variable. fopend will return
NULL a pointer upon failure.
EXAMPLE
FILE *fd;
if((fd = fopend("stdio.h", "r", "INCLUDE")) == NULL)
cant("stdio.h");
else puts("stdio.h is open for reading");
SEE ALSO fopenp(), fopeng()
FOPENG.FNC - Thu 23 Nov 89 00:20 - Page 110:
NAME
fopeng -- fopend/fopenp combination
PROTOTYPED IN: mflfiles.h
SYNOPSIS
fd = fopeng(name, mode, envar);
FILE *fd; char *name; filename char *mode;
mode char *envar; name of environment variable
DESCRIPTION
This function allows the opening of a file in other than just the
current directory. It will attempt to do the fopen in the current
directory first, and if that fails, will then expand to search by
performing a fopend() first and upon failure an fopenp(). See these
functions for details.
EXAMPLE
FILE *fd;
if((fd = fopeng("stdio.h", "r", "INCLUDE")) == NULL)
cant("stdio.h");
else puts("stdio.h is open for reading");
SEE ALSO: fopenp(), fopend()
FOPENP.FNC - Thu 23 Nov 89 00:20 - Page 111:
NAME
fopenp -- fopen a file in the PATH
PROTOTYPED IN: mflfiles.h
SYNOPSIS
fd = fopenp(name, mode);
FILE *fd;
char *name; filename
char *mode; mode
char *envar; name of environment variable
DESCRIPTION
This function allows the opening of a file in other than just
the current directory. It attempts to do the fopen in the
current directory first, and if that fails, will then expand to search
along PATH environment variable. It returns a NULL pointer upon failure.
EXAMPLE
FILE *fd;
if((fd = fopenp("foo.bar", "r")) == NULL) cant("foo.bar");
else puts("File is now opened!");
SEE ALSO fopend(), fopeng()
FTRUNC.FNC - Thu 23 Nov 89 00:20 - Page 112:
NAME
ftrunc -- truncate an fopen'ed file
PROTOTYPED IN: mflfiles.h
SYNOPSIS
result = ftrunc(fp,posn);
int result; SUCCESS or ERROR
FILE *fp; file descriptor of file to truncate
long posn; size of truncated file
DESCRIPTION
The ftrunc() function will truncate a file that has been opened as a
standard stream. It will return an ERROR if the truncation length is
longer than the existing file.
EXAMPLE
int fd;
FILE *fp;
char *fname;
long size = 100L;
fp = fopen(fname, "wb");
ftrunc(fp, size);
SEE ALSO: trunc(), truncate()
GETCODE.FNC - Thu 23 Nov 89 00:20 - Page 113:
NAME
get_code_adr -- get a function address
PROTOTYPED IN: mflsys.h
SYNOPSIS
void get_code_adr(function, segment, offset);
int *function; name of function
int *segment; destination of segment value
int *offset; destination of offset value
DESCRIPTION
This function is used to get the absolute segment and offset values
for the address of a function within a program. It is useful for
installing interrupt handlers and interfacing to assembly language
modules.
EXAMPLE
somefunc() {
}
main() {
int segment, offset;
get_code_adr(&somefunc, &segment, &offset);
printf("Address is %x:%x\n", segment, offset);
}
SEE ALSO: get_data_adr()
GETDATA.FNC - Thu 23 Nov 89 00:20 - Page 114:
NAME
get_data_adr -- get a data item address
PROTOTYPED IN: mflsys.h
SYNOPSIS
void get_data_adr(item, offset, segment);
int *item; name of data item
int *offset; destination of offset value
int *segment; destination of segment value
DESCRIPTION
This function is used to get the absolute segment and offset values
for the address of a data item within a program. It is useful for
installing interrupt handlers and interfacing to assembly language
modules.
EXAMPLE
int somenumber;
main() {
int segment, offset;
get_data_adr(&somenumber, &offset, &segment);
printf("Address is %x:%x\n", segment, offset);
}
SEE ALSO: get_code_adr()
GETDRV.FNC - Thu 23 Nov 89 00:20 - Page 115:
NAME
getdrv -- return default drive
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = chdrv(drive);
int r; returns ERROR if drive is invalid
char drive; drive ('A' - 'Z') to check
DESCRIPTION
Getdrv() is an analog of the getcwd() function which returns the
default drive letter rather than the default directory.
Note that the drive letter returned by getdrv() is always upper case.
EXAMPLE
char drive;
printf("currently on drive %c:\n", drive = getdrv());
if ('C' != drive) {
if (!chdrv('C'))
puts("changed to drive C:");
else puts("\aunable to change drives");
}
SEE ALSO: drvalid(), chdrv()
GETFT.FNC - Thu 23 Nov 89 00:20 - Page 116:
NAME
get_filetime -- get file date/time stamp
PROTOTYPED IN: mfltime.h
SYNOPSIS
#include <time.h>
void get_filetime(ptm, fh);
struct tm *ptm; pointer to tm structure
int fh; file handle of opened file
DESCRIPTION
The get_filetime() function fteches the date/time of a file. The data
from the file is placed in the specified time structure (see "time.h"),
in the same format as used by other time functions by. The file must be
opened, and a file handle passed, NOT a FILE pointer. No error is
returned from this function. The structure elements tm_wday and tm_yday
are always returned as 1, as they are generally irrelevant for file
dates. They can subsequently be calculated from the other information.
EXAMPLE
#include <time.h>
#include <mflfiles.h>
FILE *fp;
char *string;
struct tm *stamp;
/* report the date/time of a specified file on command line */
main(int argc, char *argv[])
{
if(2 != argc)
exit(0);
if(NULL == (fd = fopen(argv[1], "r")))
exit(0);
/* note conversion of FILE *fd to file handle next: */
get_filetime(stamp, (fileno(fd)));
fclose(fd);
string = asctime(stamp);
printf("File %s modified on %s\n", argv[1], string);
}
SEE ALSO: getftime()
GETFTIME.FNC - Thu 23 Nov 89 00:20 - Page 117:
NAME
getftime -- get a file's time/date stamp
PROTOTYPED IN: mfltime.h
PORTABILITY: TC
SYNOPSIS
r = getftime(fh, t);
int r; returns 0 if successful, else -1 and sets
errno
int fh; handle of file to check
struct ftime *t; pointer to file time/date stamp structure
DESCRIPTION
This routine retrieves a file's time/date stamp. See MFLTIME.H for a
description of the ftime structure.
EXAMPLE
struct ftime stamp;
int fh;
fh = open ("file.ext", O_RDONLY);
if (ERROR == getftime(fh, &stamp))
puts("can't read time/date stamp");
printf("FILE.EXT was @ %02d-%02d-%02d %02d:%02d:%02d\n",
stamp.ft_month, stamp.ft_day, stamp.ft_year + 80,
stamp.ft_hour, stamp.ft_min, stamp.ft_tsec * 2);
SEE ALSO: setftime, touch, get_filetime
GETKEY.FNC - Thu 23 Nov 89 00:20 - Page 118:
NAME
getkey -- extended keyboard fetch
PROTOTYPED IN: mflconio.h
SYNOPSIS
#include "keys.h"
r = getkey();
int r; returns keyboard value
DESCRIPTION
This function eases the reading of all keys, whether normal
or function keys. The getch() function is used to return a keyboard
value. If the first value received is 0, then a second value
is fetched and 256 (0x100) is added to flag the return value
as an extended function key. The calling program should check
for a return value greater than 255. If true, subtract 256 (or
"and" with 0xff) and consider the result as a function key.
Most function keys are defined in keys.h, and others may be user added.
EXAMPLE
This example tests for function key 3 (FK3)
#include "keys.h"
int r;
while(TRUE) {
r = getkey();
if(r < 256) {
printf("Not FK3 key");
continue;
}
else r &= 0xff;
if(r == FK3) printf("FK3 sensed!!!");
}
GETPATH.FNC - Thu 23 Nov 89 00:20 - Page 119:
NAME
getpath -- retrieve the PATH variable and parse
PROTOTYPED IN: mflfiles.h
SYNOPSIS
c = getpath(string);
int c; count of characters returned in string
char *string[]; destination for parsed string. Minimum 128
bytes, but longer paths could clobber this.
DESCRIPTION
This function extracts the PATH variable (if it exists) and makes
a "pseudo-array" at destination string. All semi-colon separators
are replaced by NULL bytes. The returned integer count totals
all characters inserted into the string including NULLS, and
should be used to determine the exact end of the string, since
a NULL byte will not determine this.
EXAMPLE
char *string[135];
int count;
count = getpath(string);
count will return as zero if no PATH is found.
GETPOS.FNC - Thu 23 Nov 89 00:20 - Page 120:
NAME
getpos -- get current cursor position
PROTOTYPED IN: mflconio.h
SYNOPSIS
position = getpos(page);
unsigned int position; returned position
int page; video page to check
DESCRIPTION
Returns the row and column of the cursor on the specified
video page. Row is in upper 8 bits of returned integer
and column in lower 8 bits. Values are in binary.
EXAMPLE
unsigned int position;
short row, column;
position = getpos(0); /* on video page 0 */
row = (position >> 8) & 0xff;
column = position & 0xff;
SEE ALSO: d_pos()
GETPREES.FNC - Thu 23 Nov 89 00:20 - Page 121:
NAME
get_press -- get waiting keypress
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = get_press(); get waiting keypress
unsigned char r; key value
DESCRIPTION
This is part of a series of functions is used to read and debounce the
four switch inputs on the joystick input port. The
analog joystick inputs are not supported.
get_press() is called to return any fully debounced input. A value of
0 indicates no input available.
Switch values are returned as an 8 bit value, with only the lowest 4
bits in use. A set bit indicates a closed switch. If multiple
keystrokes are not allowed, then get_press() will return 0, 1, 2, 4,
or 8. If multiples are allowed, then all values 0-15 (0-0x0f) may be
returned.
bit position pin number on connector
0 2
1 7
2 14
3 10
EXAMPLE
main() {
unsigned char i;
init_game(FALSE); /* allow only single switch inputs */
for ever() {
debounce(); /* call this regularly */
i = get_press();
if(i is 0) continue;
printf("switch value is %x\n", i);
}
}
SEE ALSO: init_game(), clear_game(), debounce()
GETPRESS.FNC - Thu 23 Nov 89 00:20 - Page 122:
NAME
get_press -- get waiting keypress
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = get_press(); get waiting keypress
unsigned char r; key value
DESCRIPTION
This is part of a series of functions is used to read and debounce the
four switch inputs on the joystick input port. The
analog joystick inputs are not supported.
get_press() is called to return any fully debounced input. A value of
0 indicates no input available.
Switch values are returned as an 8 bit value, with only the lowest 4
bits in use. A set bit indicates a closed switch. If multiple
keystrokes are not allowed, then get_press() will return 0, 1, 2, 4,
or 8. If multiples are allowed, then all values 0-15 (0-0x0f) may be
returned.
bit position pin number on connector
0 2
1 7
2 14
3 10
EXAMPLE
main() {
unsigned char i;
init_game(FALSE); /* allow only single switch inputs */
for ever() {
debounce(); /* call this regularly */
i = get_press();
if(i is 0) continue;
printf("switch value is %x\n", i);
}
}
SEE ALSO: init_game(), clear_game(), debounce()
GETPRTSC.FNC - Thu 23 Nov 89 00:20 - Page 123:
NAME
getPrtSc_stat -- retrieves status of last PrtSc operation
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = getPrtSc_stat();
int r; 0 if successful,
1 if screen printing is already in process,
-1 if the last screen print operation failed
DESCRIPTION
The getPrtSc_stat() function checks on the activity of any previous calls
to PrtSc().
EXAMPLE
if (0 == getPrtSc_stat()) /* make sure not already printing */
PrtSc();
SEE ALSO: PrtSc()
GTODFUNC.FNC - Thu 23 Nov 89 00:20 - Page 124:
NAME
gtodsub -- Get time of day to file pointer
PROTOTYPED IN: mfltime.h
SYNOPSIS
void gtodsub(fp);
FILE *fp;
void gtodstr(str);
char *str;
DESCRIPTION
This function reads the system date and time and sends them in a
formatted string to the specified output channel, or to a string.
EXAMPLE
gtodsub(stdout); /* send date/time to stdout */
char string[30];
gtodstr(string);
printf("date and time are %s\n", string); /* same result */
SEE ALSO: gtodstr
GTODSTR.FNC - Thu 23 Nov 89 00:20 - Page 125:
NAME
gtodstr -- Get time of day to a string
PROTOTYPED IN: mfltime.h
SYNOPSIS
void gtodstr(str);
char *str;
DESCRIPTION
This function reads the system date and time and sends them in a
formatted string to the specified output channel, or to a string.
EXAMPLE
char string[30];
gtodstr(string);
printf("date and time are %s\n", string); /* same result */
SEE ALSO: gtodsub()
GTODSUB.FNC - Thu 23 Nov 89 00:20 - Page 126:
NAME
gtodsub -- Get time of day to file pointer
PROTOTYPED IN: mfltime.h
SYNOPSIS
void gtodsub(fp);
FILE *fp;
DESCRIPTION
This function reads the system date and time and sends them in a
formatted string to the specified output channel, or to a string.
EXAMPLE
gtodsub(stdout); /* send date/time to stdout */
SEE ALSO: gtodstr()
HAS_WILD.FNC - Thu 23 Nov 89 00:20 - Page 127:
NAME
has_wild -- checks a string for DOS wildcards
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r=has_wild(str);
int r; TRUE if str contains '*' or '?', else FALSE
char *str; string to check
DESCRIPTION
The has_wild() function checks for the existence of DOS wildcard
characters ('*' and '?') in a string. It is used internally by
fnsplit().
EXAMPLE
if (has_wild("TEST.FIL")) /* returns FALSE */
...
if (has_wild("TE?T.FIL")) /* returns TRUE */
...
if (has_wild("TEST*.FIL")) /* returns TRUE */
...
SEE ALSO: fnsplit()
HSTR_I.FNC - Thu 23 Nov 89 00:20 - Page 128:
NAME
hstr_i -- make an ascii hexadecimal string into an integer
PROTOTYPED IN: mflstrng.h
SYNOPSIS
c = hstr_i(p);
char *p; string of ascii characters
unsigned int c; returned hex value
DESCRIPTION
Read a string of ascii hexadecimal digits (0-9, A-F) and create
an integer from the result. String must begin with a hex digit.
Calculation proceeds to first non-hex digit or NULL terminator.
EXAMPLE
char string[] = "1A5C*";
int result;
result = hstr_i(string);
/* result will equal 0x1A5C */
I_DSTR.FNC - Thu 23 Nov 89 00:20 - Page 129:
NAME
i_dstr -- make an integer from a decimal ascii string
PROTOTYPED IN: mflstrng.h
SYNOPSIS
c = i_dstr(p, r);
char *p; destination string pointer
int r; integer to convert
int c; count of characters in string
DESCRIPTION
Convert an integer into an ascii decimal string (unsigned).
Range is that of 16 bits unsigned, or 0-65535. The function
returns the number of characters placed in the string. The string
is NULL terminated, and must be at least six bytes long to
accomodate the longest number plus the NULL. Numbers are assumed
to be positive.
EXAMPLE
char string[6];
int count;
count = i_dstr(string, 1357);
count will equal 4
string will be "1357\0"
IBMTYPE.FNC - Thu 23 Nov 89 00:20 - Page 130:
NAME
ibmtype -- find out type of computer
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = ibmtype();
int r; r = 0 for PC or XT, 1 for PC Jr.,
2 for AT, 3 for unknown type
DESCRIPTION
This function examines the byte in ROM at F000:FFFEh.
For real IBM computers, this should be:
0xff PC
0xfe XT
0xfd JR
0xfc AT
Many close clones will also encode this byte in the above manner,
although there is no requirement for this feature.
CAVEAT
The results of this test should be taken with a grain of salt
the size of Salt Lake City. Even IBM has shipped XTs with
the PC id byte. The NOVAS AT clone correctly has 0xfc,
but the Z-NIX XT clone (which is a very close clone) has 0x05.
Don't depend too heavily on the results being really accurate.
EXAMPLE
r = ibmtype();
if(r == 2) printf("This machine is an AT, maybe!");
INDEX.FNC - Thu 23 Nov 89 00:20 - Page 131:
NAME
index -- offset of leftmost char in a string
DEFINED IN: mflstrng.h
SYNOPSIS
r = index(s,c);
int r; offset (index) of leftmost occurance of
char c in string s, -1 if unsuccessful
char *s; string to search
char c; character for which to search
DESCRIPTION
This function is part of a set of macros included in MFLSTRNG.H.
Index returns the leftmost character offset in a string. Note that
index() is available as functions in many systems and may return an
integer offset, as done here, or may simply be aliases for strchr()
and chrrchr(), respectively. It is provided here to aid portability,
but may need to be modified or undefined depending on the original
implementation.
EXAMPLES
int offset;
offset=index("ABCDEDCBA", 'C'); /* returns 2 */
offset=index("ABCDEDCBA", 'Q'); /* returns -1 */
SEE ALSO: rindex()
INITGAME.FNC - Thu 23 Nov 89 00:20 - Page 132:
NAME
init_game -- initialize and set game port mode
PROTOTYPED IN: mflsys.h
SYNOPSIS
(void)init_game(mode);
DESCRIPTION
This is part of a series of functions used to read and debounce the
four switch inputs on the joystick input port. The analog joystick
inputs are not supported. init_game() is called to setup the
processor. If its argument is TRUE, then multiple key inputs are
allowed. If FALSE, any multiple key closure will be locked out.
The game port was originally intended for playing games via
an arcade-style joystick. However, for the serious engineer,
this port is an excellent "quick and dirty" 4 bit TTL level
input port. It may be used for reading external switches,
sensors, etc.
Switch values are returned as an 8 bit value, with only the
lowest 4 bits in use. A set bit indicates a closed switch.
If multiple keystrokes are not allowed, then get_press() will
return 0, 1, 2, 4, or 8. If multiples are allowed, then
all values 0-15 (0-0x0f) may be returned.
bit position pin number on connector
0 2
1 7
2 14
3 10
EXAMPLE
main() {
unsigned char i;
init_game(FALSE); /* allow only single switch inputs */
for ever() {
debounce(); /* call this regularly */
i = get_press();
if(i is 0) continue;
printf("switch value is %x\n", i);
}
}
SEE ALSO: clear_game(), get_press(), debounce()
INSTICK.FNC - Thu 23 Nov 89 00:20 - Page 133:
NAME
installtick -- install a timer interrupt service routine
PROTOTYPED IN: mfltime.h
SYNOPSIS
void installtick(&counter);
unsigned int counter; integer to decrement
DESCRIPTION
"ticker" is not actually a C function, but a routine which is
installed on interrupt 1CH. At each interrupt (18.21 times per
second) this routine decrements an integer (16 bits) whose address was
passed during installation. The C program can load and test this
integer at any time to perform time-based operations. When the
variable is decremented to zero, it is not decremented any further;
i.e., no underflow occurs. Therefore, the integer is actually an
unsigned integer with a maximum count of 65535, or (65535/18.2)
seconds. installtick() installs the ticker on interrupt 1CH and saves
the address of the passed variable. removetick() restores the
interrupt 1CH vector to its original state. Any other routines already
installed on this vector are executed after ticker, since the ticker
chains to the original vector after execution.
EXAMPLE
int counter;
main() {
installtick(&counter);
counter = 18 * 10; /* about 10 seconds */
while(counter > 0); /* delay here */
removetick();
}
CAVEAT
It is imperative to call removetick() BEFORE terminating the program,
Otherwise, the system will crash!
SEE ALSO: ctlbrk(), criterr(), removetick()
ISCONS.FNC - Thu 23 Nov 89 00:20 - Page 134:
NAME
iscons -- is file descriptor the console
PROTOTYPED IN: mflconio.h
SYNOPSIS
r = iscons(fd);
int r; TRUE or FALSE returned
FILE *fd; file descriptor to check
DESCRIPTION
The specified file descriptor is tested to see if it refers to the
console device. TRUE (not 0) is returned if it does, and FALSE (0)
otherwise. This is a test primarily aimed at detecting if stdin or
stdout have been redirected away from the default console.
EXAMPLE
if(iscons(stdin)) puts("stdin is the keyboard");
else ("stdin is probably a file");
ISLEAP.FNC - Thu 23 Nov 89 00:20 - Page 135:
NAME
isleap -- check if year is a leap year
PROTOTYPED IN: mfltime.h
SYNOPSIS
r = isleap(year);
unsigned r; returns TRUE if leapyear, else FALSE
unsigned year; year value
DESCRIPTION
The isleap() function simply checks the specified year to return a
TRUE if the specified year is a leap year.
EXAMPLE
if(isleap(1986)) printf("This is a leap year");
else printf("This is not a leap year");
SEE ALSO: ymd_to_julian, julian_to_ymd, julian_to_wkday, julian_to_yrday
julian_to_dayname, julian_to_time, julian_to_tm, time_to_julian
tm_to_julian
ISQRT.FNC - Thu 23 Nov 89 00:20 - Page 136:
NAME
isqrt -- extract integer square root of an int
PROTOTYPED IN: mflmath.h
SYNOPSIS
result = isqrt(number);
int result; square root (truncated)
unsigned number; number whose square root to extract
DESCRIPTION
This part of a set of routines provided primarily for embedded systems
programmers. These routines extract the square root of either a short or
long integer number without the use of floating point math. Versions are
provided which will either truncate or round the result. Note that
arguments are unsigned so no error checking is done for negative inputs.
EXAMPLE
int i;
for (i = 4; i < 9; ++i)
printf("sqrt(%d) = %d, %d\n", i, isqrt(i), isqrtr(i));
/* prints: sqrt(4) = 2, 2
sqrt(5) = 2, 2
sqrt(6) = 2, 2
sqrt(7) = 2, 3
sqrt(8) = 2, 3
sqrt(9) = 3, 3 */
SEE ALSO: isqrtr(), lsqrt(), lsqrtr()
ISQRTR.FNC - Thu 23 Nov 89 00:20 - Page 137:
NAME
isqrtr -- extract integer square root of an int w/ rounding
PROTOTYPED IN: mflmath.h
SYNOPSIS
result = isqrtr(number);
int result; square root (rounded)
unsigned number; number whose square root to extract
DESCRIPTION
This is part of a set of routines provided primarily for embedded
systems programmers. These routines extract the square root of either a
short or long integer number without the use of floating point math.
Versions are provided which will either truncate or round the result.
Note that arguments are unsigned so no error checking is done for
negative inputs.
EXAMPLE
int i;
for (i = 4; i < 9; ++i)
printf("sqrt(%d) = %d, %d\n", i, isqrt(i), isqrtr(i));
/* prints: sqrt(4) = 2, 2
sqrt(5) = 2, 2
sqrt(6) = 2, 2
sqrt(7) = 2, 3
sqrt(8) = 2, 3
sqrt(9) = 3, 3 */
SEE ALSO: isqrt(), lsqrt(), lsqrtr()
JUL2DNAM.FNC - Thu 23 Nov 89 00:20 - Page 138:
NAME
julian_to_dayname -- convert Julian date to day of the week
PROTOTYPED IN: mfltime.h
SYNOPSIS
r = julian_to_dayname(julian);
char *r; day of week ("Monday", "Tuesday", etc.)
long julian; Julian (scalar) date
DESCRIPTION
This function returns a string representing the name of the day on
which a given scalar (Julian) date occured. The string returned is
taken from the active locale.
EXAMPLE
long jday;
printf("Julian date %ld fell on a %s\n",
jday, julian_to_dayname(jday));
SEE ALSO: julian_to_wkday(), setlocale(), localeconv(), ymd_to_julian(),
julian_to_ymd(), julian_to_yrday(), julian_to_time(),
julian_to_tm(), time_to_julian(), tm_to_julian
JUL2TIME.FNC - Thu 23 Nov 89 00:20 - Page 139:
NAME
julian_to_time -- convert Julian date to time_t value
PROTOTYPED IN: mfltime.h
SYNOPSIS
r = julian_to_time(julian,time);
LOGICAL r; SUCCESS or ERROR if year < 1970
long julian; Julian (scalar) date
time_t *time; date/time to convert
DESCRIPTION
This function converts scalar (Julian) dates to standard time_t date
and time values. Since Julian dates do not contain time information,
the time is reset to midnight.
EXAMPLE
long jday;
time_t time;
if (ERROR == julian_to_time(jday, &time))
puts("Can't convert dates prior to 1970");
SEE ALSO: ymd_to_julian(), julian_to_ymd(), julian_to_wkday(),
julian_to_yrday(), julian_to_dayname(), julian_to_tm(),
time_to_julian(), tm_to_julian
JUL2TM.FNC - Thu 23 Nov 89 00:20 - Page 140:
NAME
julian_to_tm -- convert Julian date to tm structure
PROTOTYPED IN: mfltime.h
SYNOPSIS
r = julian_to_tm(julian,t);
LOGICAL r; SUCCESS or ERROR if year < 1970
long julian; Julian (scalar) date
struct tm *t; date/time data to convert
DESCRIPTION
This function converts scalar (Julian) dates to standard date and
time values in a tm structure. Since Julian dates do not contain time
information, the time is reset to midnight.
EXAMPLE
long jday;
struct tm time;
if (ERROR == julian_to_time(jday, &time))
puts("Can't convert dates prior to 1970");
SEE ALSO: ymd_to_julian(), julian_to_ymd(), julian_to_wkday(),
julian_to_yrday(), julian_to_dayname(), julian_to_time(),
time_to_julian(), tm_to_julian
JUL2WDAY.FNC - Thu 23 Nov 89 00:20 - Page 141:
NAME
julian_to_wkday -- convert Julian date to day of the week
PROTOTYPED IN: mfltime.h
SYNOPSIS
r = julian_to_wkday(julian);
int r; day of week (0=Sunday, 1-Monday, etc.)
long julian; Julian (scalar) date
DESCRIPTION
This function converts scalar (Julian) dates to a day of the week in
the range of 0-6 with 0 being Sunday.
EXAMPLE
long jday;
int i;
char day[7] = {"Sun","Mon","Tue","Wed","Thu","Fri","Sat"};
i = julian_to_wkday(jday);
printf("Julian date %ld was on a %s\n", jday, day[i]);
SEE ALSO: ymd_to_julian(), julian_to_ymd(), julian_to_yrday(),
julian_to_dayname(), julian_to_time(), julian_to_tm(),
time_to_julian(), tm_to_julian
JUL2YDAY.FNC - Thu 23 Nov 89 00:20 - Page 142:
NAME
julian_to_yrday -- convert Julian date to day of the year
PROTOTYPED IN: mfltime.h
SYNOPSIS
r = julian_to_yrday(julian);
unsigned r; day of the year (1 - 366)
long julian; Julian (scalar) date
DESCRIPTION
This routine gives the day number (1-366) of a given scalar (Julian)
date.
EXAMPLE
long jday;
printf("Julian date %ld was the %drd day of the year\n",
jday, julian_to_yrday(jday));
SEE ALSO: ymd_to_julian(), julian_to_ymd(), julian_to_wkday(),
julian_to_dayname(), julian_to_time(), julian_to_tm(),
time_to_julian(), tm_to_julian
JUL2YMD.FNC - Thu 23 Nov 89 00:20 - Page 143:
NAME
julian_to_ymd -- convert Julian date to year, month, date
PROTOTYPED IN: mfltime.h
SYNOPSIS
julian_to_ymd(julian,yr,mo,day);
long julian; Julian (scalar) date
unsigned *yr; year
unsigned *mo; month
unsigned *day; date
DESCRIPTION
This function converts scalar (Julian) dates into calendar dates.
EXAMPLE
unsigned mo,day,yr;
long jday;
julian_to_ymd(jday, &yr, &mo, &day);
printf("The calendar date is %d/%d/%d\n", mo, day, yr);
SEE ALSO: ymd_to_julian(), julian_to_wkday(), julian_to_yrday(),
julian_to_dayname(), julian_to_time(), julian_to_tm(),
time_to_julian(), tm_to_julian
KB_FLUSH.FNC - Thu 23 Nov 89 00:20 - Page 144:
NAME
KB_flush -- empties keyboard buffer
DEFINED IN: mfldefs.h
SYNOPSIS
KB_flush();
DESCRIPTION
This is one of the macros included in MFLDEFS.H. It flushes the
keyboard buffer.
EXAMPLES
KB_flush();
KBSTATE.FNC - Thu 23 Nov 89 00:20 - Page 145:
NAME
_kbstate -- returns keyboard status
PROTOTYPED IN: mflconio.h
SYNOPSIS
r = _kbstate();
int r; response
DESCRIPTION
This function _kbstate() returns the keyboard status flags in a strict
binary format as they appear in memory, with :417 in the low byte and
:418 in the high byte.
EXAMPLE
int r;
r = _kbstate();
SEE ALSO: kbstatus(), setcaps(), clrcaps(), setnumlock(), clrnumlock()
KBSTATUS.FNC - Thu 23 Nov 89 00:20 - Page 146:
NAME
kbstatus -- returns specified keyboard status flag
PROTOTYPED IN: mflconio.h
SYNOPSIS
r = kbstatus(i);
int r; response
int i; which key status to return
DESCRIPTION
kbstatus(i) takes a value (fro the list below) and returns
a TRUE or FALSE condition for the selected key state.
For kbstatus the arguments are:
0 = return status of shift key(s)
1 = return insert state
2 = return caps lock state
3 = return num lock state
4 = return scroll lock state
5 = return <alt> state
6 = return <ctrl> state
EXAMPLE
setcaps();
if(kbstatus(2)) puts("Caps lock is now set");
else puts("Caps lock is NOT set");
clrcaps();
puts("Caps lock should now be off");
SEE ALSO: _kbstate(), setcaps(), clrcaps(), setnumlock(), clrnumlock()
LASTCHAR.FNC - Thu 23 Nov 89 00:20 - Page 147:
NAME
LAST_CHAR -- returns last string character
DEFINED IN: mflstrng.h
SYNOPSIS
r = LAST_CHAR(string);
char r; last character in string
char *string; string to process
DESCRIPTION
This is one of the macros included in MFLSTRNG.H. LAST_CHAR returns the
last character of a string.
EXAMPLES
char *path;
/* strip dangling backslash if not the root */
if ('\\' == LAST_CHAR(path) && ':' != NEXT_TO_LAST_CHAR(path))
LAST_CHAR(path) = '\0';
SEE ALSO: NEXT_TO_LAST_CHAR(), STRING_TERMINATOR()
LCASFILT.FNC - Thu 23 Nov 89 00:20 - Page 148:
NAME
lcase_filt -- a filter to force streams to lower case
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sfinstall(stream,lcase_filt);
int r; SUCCESS or ERROR
SFILE *stream; stream to be filtered
DESCRIPTION
Not a function, lcase_filt is an SFILTER structure used with sfinstall()
to force streams to lower case.
EXAMPLE
SFILE *infile;
infile = sfopen("file.ext", "r"); /* input from a file */
crypt_install(infile, "keytxt", 0); /* encrypt using "keytxt" */
sfinstall(infile, lcase_filt); /* after converting to LC */
SEE ALSO: sfopen(), scopen(), sclose(), sfinstall(), crypt_install(),
ucase_filt
LEFT.FNC - Thu 23 Nov 89 00:20 - Page 149:
NAME
left -- return leftmost characters
PROTOTYPED IN: mflstrng.h
SYNOPSIS
s = left(string,n);
char *s; target string
char *string; source string
int n; number of characters
DESCRIPTION
This is an emulation of the BASIC "LEFT$" function. It returns a
left-justified substring of the specified string. This function uses
the stralloc() funtion to allocate memory for the returned string.
This memory is maintained in a circular pool and reused. See
stralloc() for further information. Use strdup() or strcpy() to save
the returned string in more permanent storage.
EXAMPLE
char *a = "European";
a = left(a,2);
puts(a);
/* prints "Eu" */
SEE ALSO: right(), mid(), string_add(), str_init()), stralloc(),
str_free()
LOADSTR.FNC - Thu 23 Nov 89 00:20 - Page 150:
NAME
loadstr -- load a string with padding
PROTOTYPED IN: mflstrng.h
SYNOPSIS
void loadstr(dest, source, qty);
char *dest; string destination
char *source; source string (NULL terminated)
int qty; bytes to place in destination
DESCRIPTION
This function is similar to strcat() in that it copies a source string
to a destination string. However, if the source string is smaller
than "qty", the destination will be padded to the "qty" parameter with
spaces. In addition, the destination string will NOT be terminated by
a NULL. This is an unusual method of operation, but handy in some
cases.
EXAMPLE
char title[] = "This is a title";
char buffer[128];
loadstr(buffer, title, 80);
buffer[80] = NULL; /* add terminator */
puts(buffer); /* message will be 80 characters long,
** left justified */
LOC_CONV.FNC - Thu 23 Nov 89 00:20 - Page 151:
NAME
localeconv -- get master locale information
PROTOTYPED IN: locale.h
PORTABILITY: ANSI
SYNOPSIS
r = localeconv();
struct lconv *r; pointer to master locale
DESCRIPTION
This function returns a pointer to the master locale. See setlocale()
for details.
EXAMPLE
struct lconv my_locale;
setlocale(LC_ALL, NULL); /* returns "C" */
my_locale = localeconv(); /* copy defaults */
my_locale.TZ_txt = {"PST","PDT"};/* set Pacific Daylight Time */
my_locale.TZ_hrs=8;
my_locale.DST_flag = 1;
my_locale.s_time = "CA dreaming";
setlocale(LC_TIME, NULL); /* returns "CA dreaming" */
setlocale(LC_ALL, "C"); /* returns "C", resets master */
SEE ALSO: setlocale()
LSQRT.FNC - Thu 23 Nov 89 00:20 - Page 152:
NAME
lsqrt -- extract integer square root of a long
PROTOTYPED IN: mflmath.h
SYNOPSIS
result = lsqrt(number);
long result; square root (truncated)
unsigned long number; number whose square root to extract
DESCRIPTION
This function is part of a set of routines provided primarily for
embedded systems programmers. These routines extract the square root
of either a short or long integer number without the use of floating
point math.
EXAMPLE
int i;
for (i = 4; i < 9; ++i)
printf("sqrt(%d) = %d\n",
i, isqrt(i));
/* prints: sqrt(4) = 2
sqrt(5) = 2
sqrt(6) = 2
sqrt(7) = 2
sqrt(8) = 2
sqrt(9) = 3 */
SEE ALSO: isqrt(), isqrtr(), lsqrtr()
LSQRTR.FNC - Thu 23 Nov 89 00:20 - Page 153:
NAME
lsqrtr -- extract integer square root of a long w/ rounding
PROTOTYPED IN: mflmath.h
SYNOPSIS
result = lsqrtr(number);
long result; square root (rounded)
unsigned long number; number whose square root to extract
DESCRIPTION
This function is part of a set of routines provided primarily for
embedded systems programmers using. lsqrtr() extracts the integer
square root of a long w/ rounding.
EXAMPLE
int i;
for (i = 4; i < 9; ++i)
printf("sqrt(%d) = %d\n",
i, isqrtr(i));
/* prints: sqrt(4) = 2
sqrt(5) = 2
sqrt(6) = 2
sqrt(7) = 3
sqrt(8) = 3
sqrt(9) = 3 */
SEE ALSO: isqrt(), isqrtr(), lsqrt()
LV1WS.FNC - Thu 23 Nov 89 00:20 - Page 154:
NAME
lv1ws -- remove excess whitespace from string
PROTOTYPED IN: mflstrng.h
SYNOPSIS
void lv1ws(str);
char *str; string to modify
DESCRIPTION
This function modifies the specified string in place. White
space is defined as the space character, tab character, vertical
tab, linefeed, carriage return, and formfeed. Each white space
character is replaced with a space. Multiple white space
characters are replaced by a single space.
EXAMPLE
char string[] = " This is a \x8\x0c string \n";
lv1ws(string); /* returns " This is a string \n" */
SEE ALSO: rmlead(), rmtrail(), rmallws()
MID.FNC - Thu 23 Nov 89 00:20 - Page 155:
NAME
mid -- return embedded substring
PROTOTYPED IN: mflstrng.h
SYNOPSIS
s = mid(string,n,m);
char *s; target string
char *string; source string
int n; first character
int m; number of characters
DESCRIPTION
This is an emulation of the BASIC "MID$" function. It returns a
specified-length substring of the specified string. This function
uses the stralloc() funtion to allocate memory for the returned
string. This memory is maintained in a circular pool and reused. See
stralloc() for further information. Use strdup() or strcpy() to save
the returned string in more permanent storage.
EXAMPLE
char *a;
char *c = "Skaters";
a = mid(c,2,2);
puts(a);
/* prints "ka" */
SEE ALSO: left(), right(), string_add(), str_init(), stralloc(),
str_free()
MKBOX.FNC - Thu 23 Nov 89 00:20 - Page 156:
NAME
mkbox -- make a box on the screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
#include <mflconio.h>
void mkbox(startr, startc, width, ht, page);
int startr; starting row (top)
int startc; starting column (left)
int width; how many columns wide
int ht; how many rows high
int page; which video page (assuming
proper video mode)
DESCRIPTION
This function will make a double line box using the IBM graphics
characters on the "page" specified. The "startr" and "startc"
parameters anchor the upper left corner. The "ht" and "width" set the
dimensions. No checks are made for valid numbers. Function can be
used with both CGA and Mono cards, and with EGA cards in CGA or MONO
modes.
EXAMPLE
mkbox(0, 0, 80, 23, 0);
/* will make a box around the outside of an 80 x 24 screen. */
SEE ALSO: disp_box()
MKTONE.FNC - Thu 23 Nov 89 00:20 - Page 157:
NAME
mktone -- make a tone to the speaker
PROTOTYPED IN: mflsound.h
SYNOPSIS
#include "sound.h"
void mktone(freq, update, delay);
int freq; frequency of tone
int update speaker control command
int delay value to delay before returning
DESCRIPTION
This is a very simple function to make a tone on the IBM speaker
using the standard timer controller. The frequency is an integer
which increases the pitch of the tone with decreasing values.
the delay is an integer which is used in a very simple "for" loop
to control duration of the tone. A value of 0 is no delay.
The update integer is defined in sound.h as follows:
if update == UPDATE just send frequency and delay
if update == TOGGLE turn sound off after delay is complete
else turn sound on and leave it on when returning
Any tone may be turned off by setting freq to 0. In this case,
update and delay values are ignored and may be set to any value.
EXAMPLE
#include <mflsound.h>
mktone(1000, TOGGLE, 1000); /* make a short beep */
mktone(1000, ON, 0); /* turn a tone on */
mktone(0, 0, 0); /* turn a tone off */
mktone(2000, ON, 0); /* turn a tone on */
mktone(1000, UPDATE, 0); /* raise the pitch */
mktone(0, 0, 0); /* turn it off */
SEE ALSO: soundon(), soundoff()
MONTHIS.FNC - Thu 23 Nov 89 00:20 - Page 158:
NAME
monthis -- return a string pointer to name of month
PROTOTYPED IN: mfltime.h
SYNOPSIS
char *monthis(month);
int month; number of month 0-11
DESCRIPTION
This function returns a pointer to a character string naming
the specified month. The string is null terminated and may be
used directly or copied to another string. Month 0 is January.
EXAMPLE
printf("This is %s", monthis(7));
/* printout will be:
This is August
*/
MSECPAWS.FNC - Thu 23 Nov 89 00:20 - Page 159:
NAME
msec_pause -- pause a given number of milliseconds
PROTOTYPED IN: mfltime.h
SYNOPSIS
msec_pause(msec)
long msec; number of milliseconds to pause
DESCRIPTION
This function is part of a group of high-precision timing functions
with an accuracy of one microsecond on IBM and closely compatible
computers. To function properly, these functions require the host
system to use either an 8253 or 8254 counter/timer chip based at I/O
address 40h to generate the 18.2 Hz system interrupt used by DOS.
These functions further assume that DOS uses the four bytes at 40:6C
for its timekeeping function. These have proven to be safe assumptions
for all IBM PC's and PS/2's, Compaq's, as well as most other clone
computers and single-board computers designed for MS/PC-DOS
compatibility. The sole exception is msec_pause() which requires the
counter/timer chip but makes no other assumptions.
msec_pause() is a delay function which delays a specified number of
milliseconds.
EXAMPLE
long r;
msec_pause(r);
SEE ALSO: usec_clock(), restart_uclock(), usec_delay(), usec_difftime(),
usec_timeout(), msec_pause()
NEWEXT.FNC - Thu 23 Nov 89 00:20 - Page 160:
NAME
newext -- change a filename extension
PROTOTYPED IN: mflfiles.h
SYNOPSIS
void newext(old, new, extn);
char *old original filename string
char *new destination for new filename
char *extn new extension string
DESCRIPTION
This function will make a new filename from an existing
filename and a specified extension string. The original
filename string is left unchanged, since its base is copied to a
new string area. Nothing is returned.
EXAMPLE
char old[] = "FOOBAR.COM";
char new[14];
newext(old, new, "BIN");
After operation, the filename string in "new" will be:
FOOBAR.BIN
Character strings are NULL terminated. The original string
need not have any extension or period terminator, and may
contain a path specifier. Note that the destination string
area must be long enough to hold the new filename.
SEE ALSO: exttyp(), badext()
NXT2LAST.FNC - Thu 23 Nov 89 00:20 - Page 161:
NAME
NEXT_TO_LAST_CHAR -- returns penultimate string character
DEFINED IN: mflstrng.h
SYNOPSIS
r = NEXT_TO_LAST_CHAR(string);
char r; penultimate character in string
char *string; string to process
DESCRIPTION
This is one of the macros included in MFLSTRNG.H. It returns the next
to last character (the last character before the NULL) in a character
string.
EXAMPLES
char *path;
/* strip dangling backslash if not the root */
if ('\\' == LAST_CHAR(path) && ':' != NEXT_TO_LAST_CHAR(path))
LAST_CHAR(path) = '\0';
SEE ALSO: LAST_CHAR(), STRING_TERMINATOR()
This function is found in SMZTx.LIB for the Zortech Compiler
OFFSETOF.FNC - Thu 23 Nov 89 00:20 - Page 162:
NAME
offsetof -- returns element's position in struct
DEFINED IN: mfldefs.h
PORTABILITY: offsetof() is compatible with ANSI C and is implemented
as a macro per the draft ANSI specification.
SYNOPSIS
r = offsetof(st,el);
int r; offset within...
struct st; structure of...
void el; structure element
DESCRIPTION
The offsetof() macro is defined in the draft ANSI standard as
returning the offset of an element within a structure.
EXAMPLES
struct xyz {
long abc;
int def;
};
printf("def is at position %d\n", offsetof(xyz,def));
/* prints "4" */
OPEND.FNC - Thu 23 Nov 89 00:20 - Page 163:
NAME
openp -- open a file in the PATH
PROTOTYPED IN: mflfiles.h
SYNOPSIS
fh = opend(name, mode, envar);
int fh; file handle returned
char *name; filename
int mode; mode
char *envar name of environment variable
DESCRIPTION
This function allows the opening of a file in other than just the
current directory. It attempt the open in the current directory
first, and if that fails, will then expand to search along the PATH
environment variable. It will return -1 upon failure. The file MUST
EXIST in order for a file handle to be returned. Therefore, this
function cannot be used to create new files. See fopenp for the same
function using file descriptor structures.
EXAMPLE
int fh;
if((fh = opend("stdio.h", O_READ, "INCLUDE")) == -1)
cant("stdio.h");
else puts("stdio.h is open for reading");
SEE ALSO: opend(), openg(), fopend(), fopenp(), fopeng()
OPENDIR.FNC - Thu 23 Nov 89 00:20 - Page 164:
NAME
opendir -- open a directory for reading
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r=opendir(s1);
DOS_DIR *r; directory file pointer.
r->dd_size - number of directory entries
r->dd_loc - current entry number
char *s1; name of directory to open
DESCRIPTION
This function is similar to one found on Unix 4.2 BSD
systems. IT is designed to make reading DOS directories almost
as simple as reading normal files.
The opendir() function is an analog of fopen(). It returns a
special type of file pointer upon success or a NULL in case of
error. Possible errors include trying to open a non-directory or
exceeding the maximum number of permissible open files. Like DOS
files, there is a limit to how many directories may be open at one
time. Under the small and medium models, only 16 directories may
be opened at one time. Under the large and compact models, up to
48 directories may be open simultaneously. When the directory is
opened, the dd_size field in the DOS_DIR structure is filled in
with the total number of files, including subdirectories and "dot"
directories contained.
The opendir() function sets the DFerr global
variable depending on their return status. The error codes in
ERROR.H are used along with EOF and SUCCESS.
EXAMPLE
char *name[] = "C:\looney\bin";
DOS_DIR *dirp;
struct FIND *ffblk;
if(dirp=opendir(name))
{
printf("%s contains %d entries\n", name, dirp->dd_size);
while (ffblk=readdir(dirp))
{
printf("%3d - %s\n", dirp->dd_loc, ffblk->name);
}
closedir(dirp);
}
SEE ALSO readdir(), closedir()
OPENG.FNC - Thu 23 Nov 89 00:20 - Page 165:
NAME
openg -- opend/openp combination
PROTOTYPED IN: mflfiles.h
SYNOPSIS
int fh; file handle returned
char *name; filename
int mode; mode
char *envar; name of environment variable
DESCRIPTION
This function allows the opening of a file in other than just the
current directory. It will attempt the open in the current directory
first, and if that fails, will then expand to search along a path
specified by an environment variable. If this fails it will continue
searching along the PATH variable This function will return -1 upon
failure. The file MUST EXIST in order for a file handle to be
returned. Therefore, fopeng() cannot be used to create new files. See
fopeng for the same functions using file descriptor structures.
EXAMPLE
int fh;
if((fh = openg("stdio.h", O_READ, "INCLUDE")) == -1)
cant("stdio.h");
else puts("stdio.h is open for reading");
SEE ALSO: opend(), openg(), fopend(), fopenp(), fopeng()
OPENP.FNC - Thu 23 Nov 89 00:20 - Page 166:
NAME
openp -- open a file in the PATH
PROTOTYPED IN: mflfiles.h
SYNOPSIS
fh = openp(name, mode);
int fh; file handle returned
char *name; filename
int mode; mode
DESCRIPTION
This function allows the opening of a file in other than just the
current directory. It will attempt the open in the current directory
first, and if that fails, will then expand to search along a path
specified by an environment variable. openp() will return -1 upon
failure. The file MUST EXIST in order for a file handle to be
returned. Therefore, this function cannot be used to create new
files. See fopenp for the same functions using file descriptor
structures.
EXAMPLE
int fh;
if((fh = openp("foo.bar", O_READ)) == -1) cant("foo.bar");
else puts("File is now opened!");
SEE ALSO: opend(), openg(), fopend(), fopenp(), fopeng()
POPDIR.FNC - Thu 23 Nov 89 00:20 - Page 167:
NAME
popdir -- return to previous directory
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = popdir();
int r; returns: -1 if stack empty
0 if error
1 if success (same drive)
2 if success (changed drives)
DESCRIPTION
This functions restores the last disk directory stored with pushdir.
A static stack of eight directories is maintained
for small and medium memory models, thirty-two for large and
compact models.
EXAMPLE
if (0 < pushdir("c:utility"))
{ /* do some stuff in C:UTILITY */
if (0 < popdir())
puts("We're back home!");
else puts("oops...");
}
else puts("Couldn't change to C:UTILITY");
SEE ALSO: pushdir()
PR_CARRE.FNC - Thu 23 Nov 89 00:20 - Page 168:
NAME
pr_carret -- send a carriage return to the printer
PROTOTYPED IN: mflsys.h
SYNOPSIS
void pr_carret();
DESCRIPTION
This is part of a series of routines use the low level functions
blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly.
pr_putc() returns the same status that is returned by blprstat(). Be
sure to use pr_set() to set which LPT is to be accessed. Note that
the library defaults to LPT1:, and pr_set() may be ignored if that
printer is to be used.
EXAMPLE
pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */
pr_carret();
SEE ALSO: pr_nl(), pr_puts(), pr_line(), pr_eject(), pr_set(), pr_putc()
PR_EJECT.FNC - Thu 23 Nov 89 00:20 - Page 169:
NAME
pr_eject -- send a formfeed to the printer
PROTOTYPED IN: mflsys.h
SYNOPSIS
void pr_eject();
DESCRIPTION
This is part of a series of routines use the low level functions
blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly.
pr_putc() returns the same status that is returned by blprstat(). Be
sure to use pr_set() to set which LPT is to be accessed. Note that
the library defaults to LPT1:, and pr_set() may be ignored if that
printer is to be used.
EXAMPLE
pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */
pr_putline("Hello World");
pr_eject();
SEE ALSO: pr_nl(), pr_puts(), pr_line(), pr_carret(), pr_set(), pr_putc()
PR_NL.FNC - Thu 23 Nov 89 00:20 - Page 170:
NAME
pr_nl -- print a carriage return/line feed to printer
PROTOTYPED IN: mflsys.h
SYNOPSIS
void pr_nl();
DESCRIPTION
This is part of a series of routines use the low level functions
blpr() and blprstat() to access the LPT? ROM-BIOS drivers
directly. pr_putc() returns the same status that is returned
by blprstat(). Be sure to use pr_set() to set which LPT is
to be accessed. Note that the library defaults to LPT1:,
and pr_set() may be ignored if that printer is to be used.
EXAMPLE
pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */
pr_putline("Hello World");
pr_eject();
SEE ALSO: pr_puts(), pr_putline(), pr_eject(), pr_carret(), pr_set(),
pr_putc()
PR_PUTC.FNC - Thu 23 Nov 89 00:20 - Page 171:
NAME
pr_putc -- send a character to the printer
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = pr_putc(ch); char ch; int r; (returned status)
DESCRIPTION
This is part of a series of routines use the low level functions
blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly.
pr_putc() returns the same status that is returned by blprstat(). Be
sure to use pr_set() to set which LPT is to be accessed. Note that
the library defaults to LPT1:, and pr_set() may be ignored if that
printer is to be used.
EXAMPLE
int r;
pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */
r = pr_putc('Y');
pr_eject();
SEE ALSO: pr_nl(), pr_puts(), pr_line(), pr_eject(), pr_carret(),
pr_set()
PR_PUTLN.FNC - Thu 23 Nov 89 00:20 - Page 172:
NAME
pr_putline -- print a string, and a cr/lf to the printer
PROTOTYPED IN: mflsys.h
SYNOPSIS
pr_putline(str); char *str;
DESCRIPTION
This is part of a series of routines use the low level functions
blpr() and blprstat() to access the LPT? ROM-BIOS drivers
directly. pr_putc() returns the same status that is returned
by blprstat(). Be sure to use pr_set() to set which LPT is
to be accessed. Note that the library defaults to LPT1:,
and pr_set() may be ignored if that printer is to be used.
EXAMPLE
pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */
pr_putline("Hello World");
pr_eject();
SEE ALSO: pr_nl(), pr_puts(), pr_eject(), pr_carret(), pr_set(),
pr_putc()
PR_PUTS.FNC - Thu 23 Nov 89 00:20 - Page 173:
NAME
pr_puts -- print a string to the printer
PROTOTYPED IN: mflsys.h
SYNOPSIS
pr_puts(str); char *str;
DESCRIPTION
This is part of a series of routines use the low level functions
blpr() and blprstat() to access the LPT? ROM-BIOS drivers
directly. pr_putc() returns the same status that is returned
by blprstat(). Be sure to use pr_set() to set which LPT is
to be accessed. Note that the library defaults to LPT1:,
and pr_set() may be ignored if that printer is to be used.
EXAMPLE
pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */
pr_puts("Hello World");
SEE ALSO: pr_nl(), pr_putline(), pr_eject(), pr_carret(), pr_set(),
pr_putc()
PR_SET.FNC - Thu 23 Nov 89 00:20 - Page 174:
NAME
pr_set -- set the number of the current printer
PROTOTYPED IN: mflsys.h
SYNOPSIS
pr_set(num); int num 0, 1, or 2
DESCRIPTION
This is part of a series of routines use the low level functions
blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly.
pr_putc() returns the same status that is returned by blprstat(). Be
sure to use pr_set() to set which LPT is to be accessed. Note that
the library defaults to LPT1:, and pr_set() may be ignored if that
printer is to be used.
EXAMPLE
pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */
pr_putline("Hello World");
pr_eject();
SEE ALSO: pr_nl(), pr_puts(), pr_line(), pr_eject(), pr_carret(),
pr_putc()
PRTSC.FNC - Thu 23 Nov 89 00:20 - Page 175:
NAME
PrtSc -- prints the current text screen
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = PrtSc();
int r; SUCCESS or ERROR if printing was already in
process
DESCRIPTION
The PrtSc() function works identically to the keyboard key of the same
name - it prints the contents of the current text screen. Note that the
results when displaying graphics are undefined.
EXAMPLE
if (0 == getPrtSc_stat()) /* make sure not already printing */
PrtSc();
SEE ALSO: getPrtSc_stat()
PUSHDIR.FNC - Thu 23 Nov 89 00:20 - Page 176:
NAME
pushdir -- save current directory, then go to a new one
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = pushdir(newdir);
int r; returns: -1 if stack full
0 if error
1 if success (same drive)
2 if success (changed drives)
char *newdir; directory (drive and path) to move to
DESCRIPTION
This function saves the current disk directories prior to moving around
the disk system. A static stack of eight directories is maintained
for small and medium memory models, thirty-two for large and
compact models.
EXAMPLE
if (0 < pushdir("c:utility"))
{ /* do some stuff in C:UTILITY */
if (0 < popdir())
puts("We're back home!");
else puts("oops...");
}
else puts("Couldn't change to C:UTILITY");
SEE ALSO: popdir
RDY_RCV.FNC - Thu 23 Nov 89 00:20 - Page 177:
NAME
ready_rcv -- check for character availability
PROTOTYPED IN: mflsys.h
SYNOPSIS
x = ready_rcv(port);
DESCRIPTION
ready_rcv() is part of a set of very low level (direct port access)
subroutines to enable I/O through COM1 through COM4. Only setport()
uses BIOS int 14H. These functions are not intended to be the
ultimate in async functions, but a starting point for an integrated
set of async functions, and a means of getting at the serial port
directly for speed and to work around the problems that some "clone"
BIOS routines have in returning proper status values. File "smdefs.h"
contains #defines to handle these ports mnemonically.
ready_rcv() returns a TRUE condition if a character is waiting to be
read, but no error conditions are returned.
If the program "loop" is short and fast enough, these functions will
be ample to allow communications at up to 9600 baud. A program has
already been implemented to communicate with a prom programmer at this
rate, so it can be done. However, when the program does not poll the
receiver fast enough it is likely that characters may be lost and the
maximum usable baud rate will be lower. It is highly unlikely that
baud rates less than 2400 baud will be necessary if the program is
properly structured.
EXAMPLE
/* this routine receives characters from COM1 at one
** speed and resends them to COM2 at another speed */
unsigned char i;
setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity,
** 8-bits, 1 stop bit */
setport(SER2, 0xc3); /* set COM2 the same, but 4800 bps */
while(TRUE) {
if(!ready_rcv(SER1)) continue; /* wait for a char */
i = readchar(SER1); /* fetch it */
while(!ready_xmt(SER2));/* wait for xmtr to be ready */
writechar(SER2, i); /* then send it */
}
SEE ALSO: readchar(), ready_xmt(), setport(), writechar()
RDY_XMT.FNC - Thu 23 Nov 89 00:20 - Page 178:
NAME
ready_xmt -- check if port can accept a char to send
PROTOTYPED IN: mflsys.h
SYNOPSIS
x = ready_xmt(port);
int port; port number
int x; TRUE if condition exists, else FALSE (0)
DESCRIPTION
ready_xmt() is part of a set of very low level (direct port access)
subroutines to enable I/O through COM1 through COM4. Only setport()
uses BIOS int 14H. These functions are not intended to be the
ultimate in async functions, but a starting point for an integrated
set of async functions, and a means of getting at the serial port
directly for speed and to work around the problems that some "clone"
BIOS routines have in returning proper status values. File "smdefs.h"
contains #defines to handle these ports mnemonically.
ready_xmt() returns a TRUE condition if the transmit holding register
is empty; i.e., the transmitter can accept a character to send. In
both these functions, the status returned is a result of reading the
port status and masking all but the relevant bit. These routines will
NOT return errors such as overrun or parity.
If the program "loop" is short and fast enough, these functions will
be ample to allow communications at up to 9600 baud. A program has
already been implemented to communicate with a prom programmer at this
rate, so it can be done. However, when the program does not poll the
receiver fast enough it is likely that characters may be lost and the
maximum usable baud rate will be lower. It is highly unlikely that
baud rates less than 2400 baud will be necessary if the program is
properly structured.
RDY_XMT.FNC - Thu 23 Nov 89 00:20 - Page 179:
EXAMPLE
/* this routine receives characters from COM1 at one
** speed and resends them to COM2 at another speed */
unsigned char i;
setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity,
** 8-bits, 1 stop bit */
setport(SER2, 0xc3); /* set COM2 the same, but 4800 bps */
while(TRUE) {
if(!ready_rcv(SER1)) continue; /* wait for a char */
i = readchar(SER1); /* fetch it */
while(!ready_xmt(SER2));/* wait for xmtr to be ready */
writechar(SER2, i); /* then send it */
}
SEE ALSO: readchar(), ready_rcv(), setport(), writechar()
READCHAR.FNC - Thu 23 Nov 89 00:20 - Page 180:
NAME
readchar -- read a character from serial port
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = readchar(port);
unsigned char r; character to send or receive
int port; port number
DESCRIPTION
readchar() is part of a set of very low level (direct port access)
subroutines to enable I/O through COM1 through COM4. Only setport()
uses BIOS int 14H. These functions are not intended to be the
ultimate in async functions, but a starting point for an integrated
set of async functions, and a means of getting at the serial port
directly for speed and to work around the problems that some "clone"
BIOS routines have in returning proper status values. File "smdefs.h"
contains #defines to handle these ports mnemonically.
readchar() will return the character waiting in the receiver
register of the port. It is returned as an unsigned char
to facilitate 8-bit binary transfer protocols.
If the program "loop" is short and fast enough, these functions
will be ample to allow communications at up to 9600 baud.
A program has already been implemented to communicate with a
prom programmer at this rate, so it can be done. However,
when the program does not poll the receiver fast enough it
is likely that characters may be lost and the maximum usable
baud rate will be lower. It is highly unlikely that baud rates
less than 2400 baud will be necessary if the program is properly
structured.
READCHAR.FNC - Thu 23 Nov 89 00:20 - Page 181:
EXAMPLE
/* this routine receives characters from COM1 at one
** speed and resends them to COM2 at another speed */
unsigned char i;
setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity,
** 8-bits, 1 stop bit */
setport(SER2, 0xc3); /* set COM2 the same, but 4800 bps */
while(TRUE) {
if(!ready_rcv(SER1)) continue; /* wait for a char */
i = readchar(SER1); /* fetch it */
while(!ready_xmt(SER2));/* wait for xmtr to be ready */
writechar(SER2, i); /* then send it */
}
SEE ALSO: ready_xmt(), ready_rcv(), setport(), writechar()
READDIR.FNC - Thu 23 Nov 89 00:20 - Page 182:
NAME
readdir -- read directory entries
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r=readdir(d1);
struct FIND *r; information about this directory entry
DOS_DIR *d1; directory file pointer
DESCRIPTION
This function is part of a group of functions designed to make reading
DOS directories almost as simple as reading normal files.
The readdir() function reads sequential entries from the open
directory whose file pointer is passed, much as fgets() reads
sequential lines of text from a normal file. The dd_loc element in
the DOS_DIR structure is updated as each is read. After the last
directory entry is read (i.e. dd_loc == dd_size), subsequent calls
to readdir() will return NULL. Entries are read in normal find_t
structures as used by the other _dos_findfirst/next routines.
The readdir() function sets the DFerr global variable depending on
their return status. The error codes in ERROR.H are used along with
EOF and SUCCESS.
EXAMPLE
char *name[] = "C:\looney\bin";
DOS_DIR *dirp;
struct find_t *ffblk;
if(dirp=opendir(name))
{
printf("%s contains %d entries\n", name, dirp->dd_size);
while (ffblk=readdir(dirp))
{
printf("%3d - %s\n", dirp->dd_loc, ffblk->name);
}
closedir(dirp);
}
SEE ALSO: opendir(), closedir()
REBOOT.FNC - Thu 23 Nov 89 00:20 - Page 183:
NAME
reboot -- force a warm or cold reboot
PROTOTYPED IN: mflsys.h
SYNOPSIS
void reboot(t);
int t; type of reboot, WARM or COLD (see MFLSYS.H)
DESCRIPTION
The reboot() function does just what it says - forces a warm (Ctrl-Alt-
Del style) or cold (big red switch style) reboot.
EXAMPLE
if (disaster == minor)
reboot(WARM);
else reboot(COLD);
REPCHAR.FNC - Thu 23 Nov 89 00:20 - Page 184:
NAME
repchar -- repeat a character n times to fd
PROTOTYPED IN: mflstrng.h
SYNOPSIS
void repchar(chr, qty, fd);
char chr; character to send
int qty; number of characters to send
FILE *fd; file descriptor of output channel
DESCRIPTION
This function sends qty number of chr to fd, which is usually
stdout, stderr, or an open file. Maximum qty is 128.
If qty > 128, it will be truncated to 128. This limit is due
to an internal string buffer. For speed, the string is filled
and then fputs() is called to output the data as a string.
EXAMPLE
repchar('X', 50, stdout);
/* to output a double horizontal line: */
#include <mflconio.h>
repchar(DHLINE, 50, stdout);
RIGHT.FNC - Thu 23 Nov 89 00:20 - Page 185:
NAME
right -- return rightmost characters
PROTOTYPED IN: mflstrng.h
SYNOPSIS
s = right(string,n);
char *s; target string
char *string; source string
int n; number of characters
DESCRIPTION
This is an emulation of the BASIC "RIGHT$" function. It returns a
right-justified substring of the specified string. This function uses
the stralloc() funtion to allocate memory for the returned string.
This memory is maintained in a circular pool and reused. See
stralloc() for further information. Use strdup() or strcpy() to save
the returned string in more permanent storage.
EXAMPLE
char *a;
char *b = "Hardware";
a = right(b,2);
puts(a);
/* prints "re" */
SEE ALSO: left(), mid(), string_add(), str_init(), stralloc(),
str_free()
RINDEX.FNC - Thu 23 Nov 89 00:20 - Page 186:
NAME
rindex -- offset of rightmost char in a string
DEFINED IN: mflstrng.h
SYNOPSIS
r = rindex(s,c);
int r; offset (index) of rightmost occurance of
char c in string s, -1 if unsuccessful
char *s; string to search
char c; character for which to search
DESCRIPTION
This is one of the macros included in MFLSTRNG.H. Note that rindex()
is available as a function in many systems and may return an integer
offset, as done here, or may simply be aliases for strchr() and
chrrchr(), respectively. It is provided here to aid portability, but
may need to be modified or undefined depending on the original
implementation.
EXAMPLES
int offset;
offset=rindex("ABCDEDCBA", 'C'); /* returns 6 */
SEE ALSO: index()
RMALLWS.FNC - Thu 23 Nov 89 00:20 - Page 187:
NAME
rmallws -- remove all whitespace from string
PROTOTYPED IN: mflstrng.h
SYNOPSIS
str=rmallws(str);
char *str; string to modify
DESCRIPTION
This string function modifys the specified string in place. White
space is defined as the space character, tab character, vertical tab,
linefeed, carriage return, and formfeed. String size is limited to
255 characters, although the source code can be modified to increase
or decrease that. If the string exceeds that size, it is truncated.
Note that all strings are modified "in place" and all functions return
a pointer to the modified string.
EXAMPLE
char string[] = " This is a string \n";
rmallws(string); /* returns "Thisisastring" */
SEE ALSO: rmlead(), rmtrail(), lv1ws()
RMLEAD.FNC - Thu 23 Nov 89 00:20 - Page 188:
NAME
rmlead -- remove leading whitespace from string
PROTOTYPED IN: mflstrng.h
SYNOPSIS
str=rmlead(str);
char *str; string to modify
DESCRIPTION
This string function will modify the specified string in place.
White space is defined as the space character, tab character, vertical
tab, linefeed, carriage return, and formfeed. String size is limited
to 255 characters, although the source code can be modified to
increase or decrease that. If the string exceeds that size, it is
truncated. Note that all strings are modified "in place" and all
functions return a pointer to the modified string.
EXAMPLE
char string[] = " This is a string \n";
rmlead(string); /* returns "This is a string \n" */
SEE ALSO rmallws(), rmtrail(), lv1ws()
RMTICK.FNC - Thu 23 Nov 89 00:20 - Page 189:
NAME
removetick -- remove a timer interrupt service routine
PROTOTYPED IN: mfltime.h
SYNOPSIS
void removetick();
DESCRIPTION
"ticker" is not actually a C function, but a routine which is
installed on interrupt 1CH. At each interrupt (18.21 times per
second) this routine decrements an integer (16 bits) whose address was
passed during installation. The C program can load and test this
integer at any time to perform time-based operations. When the
variable is decremented to zero, it is not decremented any further;
i.e., no underflow occurs. Therefore, the integer is actually an
unsigned integer with a maximum count of 65535, or (65535/18.2)
seconds. installtick() installs the ticker on interrupt 1CH and saves
the address of the passed variable. removetick() restores the
interrupt 1CH vector to its original state. Any other routines already
installed on this vector are executed after ticker, since the ticker
chains to the original vector after execution.
EXAMPLE
int counter;
main() {
installtick(&counter);
counter = 18 * 10; /* about 10 seconds */
while(counter > 0); /* delay here */
removetick();
}
CAVEAT
It is imperative to call removetick() BEFORE terminating the program,
Otherwise, the system will crash!
SEE ALSO: ctlbrk(), criterr(), installtick()
RMTRAIL.FNC - Thu 23 Nov 89 00:20 - Page 190:
NAME
rmtrail -- remove trailing whitespace from string
PROTOTYPED IN: mflstrng.h
SYNOPSIS
str=rmtrail(str);
char *str; string to modify
DESCRIPTION
This string function will modify the specified string in place.
White space is defined as the space character, tab character, vertical
tab, linefeed, carriage return, and formfeed. String size is limited
to 255 characters, although the source code can be modified to
increase or decrease that. If the string exceeds that size, it is
truncated. Note that all strings are modified "in place" and all
functions return a pointer to the modified string.
EXAMPLE
char string[] = " This is a string \n";
rmtail(string); /* returns " This is a string" */
SEE ALSO: rmallws(), rmlead(), lv1ws()
RSTUCLK.FNC - Thu 23 Nov 89 00:20 - Page 191:
NAME
restart_uclock -- re-initialize the microsecond clock
PROTOTYPED IN: mfltime.h
SYNOPSIS
restart_uclock();
DESCRIPTION
This is part of a group of functions that implement timing functions
with an accuracy of one microsecond on IBM and closely compatible
computers. To function properly, these functions require the host
system to use either an 8253 or 8254 counter/timer chip based at I/O
address 40h to generate the 18.2 Hz system interrupt used by DOS.
These functions further assume that DOS uses the four bytes at 40:6C
for its timekeeping function. These have proven to be safe assumptions
for all IBM PC's and PS/2's, Compaq's, as well as most other clone
computers and single-board computers designed for MS/PC-DOS
compatibility. The sole exception is msec_pause() which requires the
counter/timer chip but makes no other assumptions.
The usec_clock() function relies on data which rolls over at
midnight each day and can handle this. However, if a program is to
run continuously for many days, it becomes necessary to take
action to prevent internal overflow. This may be done by resetting
the internal registers used by usec_clock() at least once per day
by calling restart_uclock().
EXAMPLE
restart_uclock();
SEE ALSO: usec_clock(), restart_uclock(), usec_delay(),
usec_difftime(), usec_timeout(), msec_pause()
SCLOSE.FNC - Thu 23 Nov 89 00:20 - Page 192:
NAME
sclose -- close a stream
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sclose(stream);
int r; SUCCESS or ERROR
SFILE *stream; stream to close
DESCRIPTION
The sclose() function is used to close streams opened with either the
sfopen() or scopen() functions.
EXAMPLE
int serial_out();
SFILE *infile, *outfile;
infile = sfopen("file.ext", "r"); /* input from a file */
outfile = scopen(serial_out, "w"); /* output to serial I/O */
...
if (SUCCESS != sclose(infile))
puts("couldn't close file.ext");
if (SUCCESS != sclose(outfile))
puts("couldn't close serial I/O");
SEE ALSO: sfopen(), scopen()
SCOPEN.FNC - Thu 23 Nov 89 00:20 - Page 193:
NAME
scopen -- open a channel stream
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = scopen(gfunc,ufinc,mode);
SFILE *r; pointer to an SFILE record - equivalent to
fopen's FILE pointer - NULL in case of error
int (*gfunc)(); function to call when reading (mode includes "r")
or writing (mode includes "w") streams
int (*ufunc)(); function to call when "ungetting" (mode includes
"r" only) characters previously read from streams
char *mode; mode in which to open the streeam
DESCRIPTION
The scopen() function is used to open streams to channels. Comparable to
sfopen(), scopen() is a general-purpose function to allow user-defined
functions to interface with the rest of the MicroFirm Function Library's
stream I/O package.
EXAMPLE
int is_char_rdy(), get_serial(); /* from some serial comms */
SFILE *infile, *outfile;
char buf[128];
int s_in(void)
{
while (!is_char_rdy())
;
return get_serial();
}
int s_unget(int ch)
{
return serial_unget(ch);
}
infile = scopen(s_in,s_unget,"r"); /* input from serial I/O */
outfile = sfopen("file.ext", "w"); /* output to a file */
sfinstall(infile, ucase_filt); /* convert input to U.C. */
crypt_install(outfile, "mykey", 0); /* encrypt output stream */
sfgets(buf, 128, infile); /* read a string */
sfputs(buf, outfile); /* write it out */
SEE ALSO: sfopen(), sclose()
SET_LOC.FNC - Thu 23 Nov 89 00:20 - Page 194:
NAME
setlocale -- set country-specific information
PROTOTYPED IN: locale.h
PORTABILITY: ANSI
SYNOPSIS
r = setlocale(category,locale);
char *r; current locale spec
int category; type of locale info to be set
char *locale; locale specification
DESCRIPTION
The setlocale() function specified in the ANSI draft. Although all
categories are currently recognized, not all are supported.
As defined by ANSI and in LOCALE.H, the lconv structure may be
envisioned as a concatenation of several sub-structures containing
information which will vary depending on locale. The valid
categories are defined by `LC_' macros as follows:
LC_ALL This sets the entire lconv structure including all
sub-categories.
LC_COLLATE Not supported, this is designed to vary the action
of the string comparison functions.
LC_CTYPE Not supported, this designed to affect the action
of functions defined in CTYPE.H.
LC_MONETARY This contains formatting information for
expressing monetary values (see below).
LC_NUMERIC This contains formatting information for
expressing arithmetic values (see below).
LC_TIME This contains formatting information used
by strftime() and julian_to_dayname() (see below).
To set an active locale, setlocale() is called with the category of
locale to set and the name of the locale to set. If the name of the
locale passed is NULL, the name of the currently active locale is
returned. If the name of the locale passed is empty (""), the
default locale is set (see below). Calling setlocale() returns the
locale name of the locale which was set. Currently specified
locales include:
"C" ANSI-mandated minimum locale, suitable for
minimum-functionality usage in English-speaking
countries.
"USA" The default (empty locale name string) locale.
SET_LOC.FNC - Thu 23 Nov 89 00:20 - Page 195:
To set a new or non-English locale, you must first add a structure
of type lconv to the _lconv[] array in LOCALE.C, setting each of
its category names (fields beginning with "s_") to the name of your
new locale. This structure elements are as follows:
char *s_all Name of the locale returned by LC_ALL
char *s_collate Name of the locale returned by LC_COLLATE
char *s_ctype Name of the locale returned by LC_CTYPE
char *s_monetary Name of the locale returned by LC_MONETARY
char *currency_symbol String containing the locale's currency
symbol, e.g. "$" in the U.S.
char *int_curr_symbol String containing the locale's
international currency symbol, e.g. "USD"
in the U.S.
char *mon_decimal_point String containing the locale's decimal
point, e.g. "." in the U.S.
char *mon_thousands_sep String containing the locale's thousands
separator, e.g. "," in the U.S.
char *mon_grouping Although this is a string, only the first
character's ASCII value is used to
determine the size of character groupings in
specifying monetary values, i.e. for the
U.S. use "\3" to specify 3-character
groupings.
char *positive_sign String containing the positive symbol,
e.g. "+" in the U.S.
char *negative_sign String containing the negative symbol,
e.g. "-" in the U.S.
char int_frac_digits The number of digits to display for
fractional international monetary
quantities, e.g. 2 for the U.S.
char frac_digits The number of digits to display for
fractional monetary quantities, e.g. 2 for
the U.S.
char p_cs_precedes Whether the currency symbol precedes (1)
or follows (0) the value for positive
monetary values.
char n_cs_precedes Whether the currency symbol precedes (1)
or follows (0) the value for negative
monetary values.
char p_sep_by_space Whether the currency symbol is separated
by a space (1) or not (0) for positive
monetary values.
char n_sep_by_space Whether the currency symbol is separated
by a space (1) or not (0) for negative
monetary values.
char p_sign_posn Whether, for positive monetary values:
(0) parentheses surround the value and the
currency symbol,
(1) the positive sign precedes the value
and the currency symbol,
(2) the positive sign follows the value
and the currency symbol,
(3) the positive sign immediately precedes
the currency symbol, or
SET_LOC.FNC - Thu 23 Nov 89 00:20 - Page 196:
(4) the positive sign immediately follows
the currency symbol.
char n_sign_posn Whether, for negative monetary values:
(0) parentheses surround the value and the
currency symbol,
(1) the negative sign precedes the value
and the currency symbol,
(2) the negative sign follows the value
and the currency symbol,
(3) the negative sign immediately precedes
the currency symbol, or
(4) the negative sign immediately follows
the currency symbol.
char *s_numeric Name of the locale returned by LC_NUMERIC
char *decimal_point String containing the locale's decimal
point, e.g. "." in the U.S.
char *thousands_sep String containing the locale's thousands
separator, e.g. "," in the U.S.
char *grouping Although this is a string, only the first
character's ASCII value is used to
determine the size of character groupings in
specifying arithmetic values, i.e. for the
U.S. use "\3" to specify 3-character
groupings.
char *s_time Name of the locale returned by LC_TIME
char *day[7][2] An array of weekday names, starting with
Sunday, and their abbreviations.
char *month[12][2] An array of month names, starting with
January, and their abbreviations.
int TZ_secs Seconds to add to GMT to get local standard
time.
int DST_flag 0 if local standard time, 1 if local
daylight time.
char *TZ_txt[2] The local time zone names, both normal
([0]) and daylight ([1]). Defaults to
"CST", "CDT".
char tim_sep Character used to separate time fields
(':').
char *p_FMTA Morning AM/PM indicator ("AM").
char *p_FMTP Evening AM/PM indicator ("PM").
char *c_FORMAT strftime() format string for standard
display. See STRFTIME.C for exact usage.
char *x_FORMAT strftime() format string for date display.
char *X_FORMAT strftime() format string for time display.
char fmt_24 Indicates formatting of hours between midnight
and 1:00 AM. Zero indicates to display as
00:mm:ss, non-zero indicates to use 24:mm:ss.
SET_LOC.FNC - Thu 23 Nov 89 00:20 - Page 197:
LOCALE.C maintains a master locale for use by applications
programs. This allows different locale categories to be mixed in
the master locale. For example, the "USA" locale may be specified
for monetary value formatting while the default "C" locale might be
used for numeric values, thus avoiding the grouping and thousands
separators in the LC_NUMERIC category of the "USA" locale. To
access the master locale, the function localeconv() is called which
returns a pointer to the master locale.
The strftime() function uses an additional feature of setlocale(), the
ability to use environment variables. Two environment variables are
used, "TIMEZONE" and "DAYLIGHT". The TIMEZONE variable takes the form
"NNN[+/-]TT[TTTT]DDD" where "NNN" is the name for the normal time zone,
"DDD" is the name when using daylight savings time, and "TT[TTTT]" is
the local offset from GMT in either hours (range: -24 to 24) or seconds.
For example to set Pacific Time, use:
"SET TIMEZONE=PST8" sets PST
"SET TIMEZONE=PST9PDT" sets PDT
The DAYLIGHT variable is set to either "0" or a non-zero numeric value
to indicate whether daylight savings time is in effect. For example, if
TIMEZONE were set as above for PDT, the use of PST could be forced by:
"SET DAYLIGHT=0"
NOTES: When using the "USA" locale, "TZ_hrs" and "DST_flag" are set
to default values of 6 and 0, respectively, corresponding to
CST.
When using the default "C" locale, "TZ_secs" and "DST_flag" are set to
default values of 0 and 0, respectively.
When using strftime(), note that the DST_flag in the master locale
rather than the "tm_isdst" field of the local tm structure determines
the time zone display.
EXAMPLE
struct lconv my_locale;
setlocale(LC_ALL, NULL); /* returns "C" */
my_locale = localeconv(); /* copy defaults */
my_locale.TZ_txt = {"PST","PDT"};/* set Pacific Daylight Time */
my_locale.TZ_secs=8*3600;
my_locale.DST_flag = 1;
my_locale.s_time = "CA dreaming";
setlocale(LC_TIME, NULL); /* returns "CA dreaming" */
setlocale(LC_ALL, "C"); /* returns "C", resets master */
SEE ALSO: localeconv(), strftime(), tzset()
SETCAPS.FNC - Thu 23 Nov 89 00:20 - Page 198:
NAME
setcaps -- set the capslock status on
PROTOTYPED IN: mflconio.h
SYNOPSIS
setcaps();
DESCRIPTION
This is part of a set of functions which manipulate the keyboardf
status flags at 0000:417 and 0000:418. setcaps() will force the caps
lock flag ON, and clrcaps will force it off.
EXAMPLE
setcaps();
if(kbstate(2)) puts("Caps lock is now set");
else puts("Caps lock is NOT set");
clrcaps();
puts("Caps lock should now be off");
SEE ALSO _kbstate(), _kbstatus(), setnumlock(), clrnumlock(), clrcaps()
SETDTR.FNC - Thu 23 Nov 89 00:20 - Page 199:
NAME
setdtr -- set state of data terminal ready flag
PROTOTYPED IN: mflsys.h
SYNOPSIS
void setdtr(port, mode);
int port; 0, 1, 2, or 3 (for COM1-COM4)
int mode; TRUE to set flag, FALSE to clear flag
DESCRIPTION
This assembly language function provides direct access to the serial
communications chips for the fastest access possible. Each function
sets a particular communications output bit to the condition stated by
"mode". The port parameter may be specified as integers 0-3, or SER1
to SER4 as defined in MFLDEFS.H.
EXAMPLE
int sport; /* serial port */
sport = SER2; /* let it point to COM2 */
setdtr(sport, YES); /* take the modem offhook */
SEE ALSO: setdtr()
SETFTIME.FNC - Thu 23 Nov 89 00:20 - Page 200:
NAME
setftime -- set a file's time/date stamp
PROTOTYPED IN: mfltime.h
PORTABILITY: TC
SYNOPSIS
r = setftime(fh, t);
int r; returns 0 if successful, else -1 and sets
errno
int fh; handle of file to check
struct ftime *t; pointer to file time/date stamp structure
DESCRIPTION
This routine sets a file's time/date stamp. See MFLTIME.H for a
description of the ftime structure.
EXAMPLE
struct ftime then;
int fh;
fh = open ("file.ext", O_RDONLY);
if (ERROR == setftime(fh, &then))
puts("couldn't reset time/date stamp");
}
SEE ALSO: getftime(), touch(), get_filetime()
SETNMLOC.FNC - Thu 23 Nov 89 00:20 - Page 201:
NAME
setnumlock -- Turns Numlock status flag on
PROTOTYPED IN: mflconio.h
SYNOPSIS
setnumlock();
DESCRIPTION
This is one of a set of functions which manipulate the keyboardf
status flags at 0000:417 and 0000:418. setnumlock() sets the numlock
status flag on.
EXAMPLE
setnumlock();
if(kbstate(2)) puts("Num lock is now set");
else puts("Num lock is NOT set");
clrnumlock();
puts("Num lock should now be off");
SEE ALSO: clrcaps(), setcaps(), clrnumlock(), _kbstate(), _kbstatus()
SETPORT.FNC - Thu 23 Nov 89 00:20 - Page 202:
NAME
setport -- set port configuration
PROTOTYPED IN: mflsys.h
SYNOPSIS
(void) setport(port, r);
int port; port number
int x; TRUE if condition exists, else FALSE (0)
DESCRIPTION
This is part of a set of very low level (direct port access)
subroutines to enable I/O through COM1 through COM4. Only setport()
uses BIOS int 14H. These functions are not intended to be the
ultimate in async functions, but a starting point for an integrated
set of async functions, and a means of getting at the serial port
directly for speed and to work around the problems that some "clone"
BIOS routines have in returning proper status values. File "smdefs.h"
contains #defines to handle these ports mnemonically.
The value to use for the setport() function is an 8-bit
value, bitwise organized as follows:
bits 1,0: 10 = 7-bit data, 11 = 8-bit data
bit 2: 0 = 1 stop bit, 1 = 2 stop bits
bits 4,3: x0 = No Parity, 01 = odd, 11 = even
bits 7,6,5: baud rate:
000 = 110 baud (use 2 stop bits)
001 = 150 baud
010 = 300 baud
011 = 600 baud
100 = 1200 baud
101 = 2400 baud
110 = 4800 baud
111 = 9600 baud
SETPORT.FNC - Thu 23 Nov 89 00:20 - Page 203:
EXAMPLE
/* this routine receives characters from COM1 at one
** speed and resends them to COM2 at another speed */
unsigned char i;
setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity,
** 8-bits, 1 stop bit */
setport(SER2, 0xc3); /* set COM2 the same, except 4800 baud */
while(TRUE) {
if(!ready_rcv(SER1)) continue; /* wait for a char */
i = readchar(SER1); /* fetch it */
while(!ready_xmt(SER2));/* wait for xmittr to be ready */
writechar(SER2, i); /* then send it */
}
SEE ALSO: ready_rcv(), ready_xmt()
SETRTS.FNC - Thu 23 Nov 89 00:20 - Page 204:
NAME
setrts -- set state of ready to send flag
PROTOTYPED IN: mflsys.h
SYNOPSIS
void setrts(port, mode);
int port; 0, 1, 2, or 3 (for COM1-COM4)
int mode; TRUE to set flag, FALSE to clear flag
DESCRIPTION
This assembly language function provides direct access to the serial
communications chips for the fastest access possible. The function
sets the state of the ready to send flag. The port parameter may be
specified as integers 0-3, or SER1 to SER4 as defined in <MFLDEFS.H>.
EXAMPLE
int sport; /* serial port */
sport = SER2; /* let it point to COM2 */
setrts(sport, YES); /* take the modem offhook */
SEE ALSO: setdtr()
SFGETC.FNC - Thu 23 Nov 89 00:20 - Page 205:
NAME
sfgetc -- get a character from a stream
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sfgetc(stream);
int r; character or EOF
SFILE *stream; stream from which to read
DESCRIPTION
The sfgetc() function is an exact analog of the normal fgetc() function
except that it is passed an SFILE pointer rather than a FILE pointer.
EXAMPLE
SFILE *infile;
int ch;
infile = sfopen("file.ext", "r"); /* input from a file */
if (EOF == (ch = sfgetc(infile)))
puts("all done");
SEE ALSO: sfopen(), scopen(), sclose(), sfgets(), sfread(), sfputc(),
sfputs(), sfwrite(), sfinstall(), crypt_install(), ucase_filt,
lcase_filt
SFGETS.FNC - Thu 23 Nov 89 00:20 - Page 206:
NAME
sfgets -- get a string from a stream
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sfgetc(buf,n,stream);
char *r; string which was read
char *buf; buffer to receive string
int n; maximum size plus 1 of received string
SFILE *stream; stream from which to read
DESCRIPTION
The sfgets() function is an exact analog of the normal fgets() function
except that it is passed an SFILE pointer rather than a FILE pointer.
EXAMPLE
SFILE *infile;
char str[128];
infile = sfopen("file.ext", "r"); /* input from a file */
if (NULL == sfgets(str, 128, infile)))
puts("all done");
SEE ALSO: sfopen(), scopen(), sclose(), sfgets(), sfread(), sfputc(),
sfputs(), sfwrite(), sfinstall(), crypt_install(), ucase_filt,
lcase_filt
SFINST.FNC - Thu 23 Nov 89 00:20 - Page 207:
NAME
sfinstall -- install a user-defined stream filter
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sfgetc(stream,filt);
int r; SUCCESS or ERROR
SFILE *stream; stream to be filtered
SFILTER *filt; filter to install
DESCRIPTION
The sfinstall() function allows user-defined filters to be installed in
any stream opened using sfopen() or scopen(). Simple filters are
installed by simply filling in the chain and (optionally) flush fields
of an SFILTER structure and passing it to sfinstalll(). More complex
filters which require initialization, etc. require dedicated
installation functions which internally must call sfinstall(). An
example of such a filter is the data encryption filter, installed using
the crypt_install() function.
Properly written filters can be chained indefinitely. Filter functions
are invoked in a last-installed, first-executed sequence. When a stream
is closed, the flush functions are invoked in the same order to clear
any pending operations.
EXAMPLE
SFILE *infile;
infile = sfopen("file.ext", "r"); /* input from a file */
crypt_install(infile, "keytxt", 0); /* encrypt using "keytxt" */
sfinstall(infile, ucase_filt); /* after converting to UC */
SEE ALSO: sfopen(), scopen(), sclose(), crypt_install(), ucase_filt,
lcase_filt
SFOPEN.FNC - Thu 23 Nov 89 00:20 - Page 208:
NAME
sfopen -- open a stream
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sfopen(fname,mode);
SFILE *r; pointer to an SFILE record - equivalent to fopen's
FILE pointer - NULL in case of error
char *fname; name of the file or stream to open
char *mode; mode in which to open the streeam
DESCRIPTION
The sfopen() function is an almost exact analog of the standard fopen()
function, so it is appropriate to describe their differences:
o sfopen() returns an SFILE pointer while fopen() returns a FILE pointer.
o sfopen'ed files and streams are always opened in binary mode
o sfopen'ed files and streams are always read and written sequentially,
i.e. there are no positioning commands comparable to fseek()
o sfopen'ing a file or stream in append mode is not permitted
o sfopen'ed files and streams allow user-defined filters to be installed,
comparable to DOS command line pipes
o a comparable function, scopen() exists to open streams to channels,
e.g. an SFILE pointer may transparently refer to an interrupt-driven
serial I/O package
EXAMPLE
SFILE *infile;
if (NULL == (infile = sfopen("file.ext", "r+")))
puts("couldn't open file.ext");
SEE ALSO: scopen(), sclose()
SFPUTC.FNC - Thu 23 Nov 89 00:20 - Page 209:
NAME
sfputc -- put a character to a stream
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sfputc(ch,stream);
int r; character or EOF in case of error
int ch; character to output
SFILE *stream; stream to write
DESCRIPTION
The sfputc() function is an exact analog of the normal fputc() function
except that it is passed an SFILE pointer rather than a FILE pointer.
EXAMPLE
SFILE *outfile;
outfile = sfopen("file.ext", "w"); /* output to a file */
if (EOF == sfputc('x', outfile))
puts("oops");
SEE ALSO: sfopen(), scopen(), sclose(), sfgetc(), sfgets(), sfread(),
sfputs(), sfwrite(), sfinstall(), crypt_install(), ucase_filt,
lcase_filt
SFPUTS.FNC - Thu 23 Nov 89 00:20 - Page 210:
NAME
sfputs -- put a string to a stream
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sfputc(s,stream);
int r; SUCCESS if succesful
char *s; string to output
SFILE *stream; stream to write
DESCRIPTION
The sfputs() function is an exact analog of the normal fputs() function
except that it is passed an SFILE pointer rather than a FILE pointer.
EXAMPLE
SFILE *outfile;
outfile = sfopen("file.ext", "w"); /* output to a file */
if (EOF == sfputc("test", outfile))
puts("oops");
SEE ALSO: sfopen(), scopen(), sclose(), sfgetc(), sfgets(), sfread(),
sfputc(), sfwrite(), sfinstall(), crypt_install(), ucase_filt,
lcase_filt
SFREAD.FNC - Thu 23 Nov 89 00:20 - Page 211:
NAME
sfread -- read a buffer from a stream
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sfgetc(buf,size,n,stream);
int r; number of complete elements which were read
char *buf; buffer to receive data
unsigned size; size of elements to be read
unsigned n; number of elements to read
SFILE *stream; stream from which to read
DESCRIPTION
The sfread() function is an exact analog of the normal fread() function
except that it is passed an SFILE pointer rather than a FILE pointer.
EXAMPLE
SFILE *infile;
char buf[1024];
infile = sfopen("file.ext", "r"); /* input from a file */
if (1024 != sfread(buf, 8, 128, infile))
puts("all done");
SEE ALSO: sfopen(), scopen(), sclose(), sfgetc(), sfgets(), sfputc(),
sfputs(), sfwrite(), sfinstall(), crypt_install(), ucase_filt,
lcase_filt
SFWRITE.FNC - Thu 23 Nov 89 00:20 - Page 212:
NAME
sfwrite -- write a buffer from a stream
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r = sfgetc(buf,size,n,stream);
int r; number of complete elements which were written
char *buf; buffer to write
unsigned size; size of elements to write
unsigned n; number of elements to write
SFILE *stream; stream to write
DESCRIPTION
The sfwrite() function is an exact analog of the normal fwrite() function
except that it is passed an SFILE pointer rather than a FILE pointer.
EXAMPLE
SFILE *outfile;
char buf[1024];
outfile = sfopen("file.ext", "w"); /* output to a file */
if (1024 != sfwrite(buf, 8, 128, outfile))
puts("oops");
SEE ALSO: sfopen(), scopen(), sclose(), sfgetc(), sfgets(), sfread(),
sfputc(), sfputs(), sfinstall(), crypt_install(), ucase_filt,
lcase_filt
SOUNDOFF.FNC - Thu 23 Nov 89 00:20 - Page 213:
NAME
soundoff -- turn off the speaker
PROTOTYPED IN: mflsound.h
SYNOPSIS
void soundoff();
DESCRIPTION
This is a very low level function to manipulate the speaker port
control. It may be used with any function, but was developed for use
with the mktone() function. Timer values should be set before turning
the speaker on.
SEE ALSO: soundon()
SOUNDON.FNC - Thu 23 Nov 89 00:20 - Page 214:
NAME
soundon -- turn on the speaker
PROTOTYPED IN: mflsound.h
SYNOPSIS
void soundon();
DESCRIPTION
This is a very low level function to manipulate the speaker
port control. It may be used with any function, but was developed
for use with the mktone() function. Timer values should be set
before turning the speaker on.
SEE ALSO: soundoff()
STR_ADD.FNC - Thu 23 Nov 89 00:20 - Page 215:
NAME
string_add -- BASIC-style string concatenation
PROTOTYPED IN: mflstrng.h
SYNOPSIS
s = char *string_add(string,...,NULL);
char *s; target string
char *string; source string
DESCRIPTION
This is an emulation of the BASIC "A$=B$+C$" facility. It returns a
concatenated string of its argument strings. This function uses
the stralloc() funtion to allocate memory for the returned string.
This memory is maintained in a circular pool and reused. See
stralloc() for further information. Use strdup() or strcpy() to save
the returned string in more permanent storage.
EXAMPLE
char *a = "European";
char *b = "Hardware";
char *c = "Skaters";
a = string_add(left(a,2),right(b,2),mid(c,2,2),NULL));
puts(a);
/* prints "Eureka" */
SEE ALSO: right(), left(), mid(), str_init(), stralloc(), str_free()
STR_FREE.FNC - Thu 23 Nov 89 00:20 - Page 216:
NAME
str_free -- free's the string pool
PROTOTYPED IN: mflstrng.h
SYNOPSIS
str_free();
DESCRIPTION
The str_free()function frees the memory used by stralloc() as a
circular buffer of strings.
EXAMPLE
str_free();
SEE ALSO: str_init(), stralloc()
STR_INIT.FNC - Thu 23 Nov 89 00:20 - Page 217:
NAME
str_init -- initialize a string pool
PROTOTYPED IN: mflstrng.h
SYNOPSIS
r = str_init(size,number);
int r; returns zero if successful, else
ERROR
int size; size of pre-allocated strings
int number; number of pre-allocated strings (must
be <= 128 in S or M models, or <=512
in C and L models)
DESCRIPTION
The underlying function for the BASIC-like string handling package is
stralloc which maintains a pool of character buffers which it
dispenses as requested and constantly reuses and reallocates as
required. As a default, stralloc maintains a circular buffer of 16
strings in Tiny, Small, and Medium models and 64 strings in Compact
and Large models. These start out very small and grow as required.
Should you wish to expand the number of strings or wish to
pre-allocate strings of a given minimum size to avoid re- allocation,
the str_init() function allows setting both parameters. You should
use str_init() and set the global variable "STRALLOC_OK" to "FALSE"
prior to using any of the other functions in any routine which
explicitly calls free() to de-allocate memory. The str_init()
function internally calls str_free() which may be used to free all
memory in use by these functions. It is NOT generally recommended
that str_free() be called by an application program since "holes" in
memory may be created that DOS is later unable to resolve.
EXAMPLE
str_init(81, 50); /* Pre-allocate 50-80 char strings */
SEE ALSO: stralloc(), str_free()
STR_TERM.FNC - Thu 23 Nov 89 00:20 - Page 218:
NAME
STRING_TERMINATOR -- returns terminating '\0'
DEFINED IN: mflstrng.h
SYNOPSIS
r = STRING_TERMINATOR(string);
char r; terminating '\0' in string
char *string; string to process
DESCRIPTION
This is one of the macros included in MFLSTRNG.H. It simply returns
evidence of a terminating '\0' in a string. It is occasionally useful when
concatenating or processing strings to refer to `&STRING_TERMINATOR(str)'
which is a pointer to the end of `str'.
EXAMPLES
char *string = "Hello World\0";
if(STRING_TERMINATOR(string) == '\0')
puts(Yep, it's got a terminator);
SEE ALSO: LAST_CHAR(), NEXT_TO_LAST_CHAR()
STRALLOC.FNC - Thu 23 Nov 89 00:20 - Page 219:
NAME
stralloc -- allocate a string from a string pool
PROTOTYPED IN: mflstrng.h
SYNOPSIS
extern LOGICAL STRALLOC_OK;
s = stralloc(size);
char *s; returns a char buffer of length size,
else NULL if out of memory
int size; length of desired string
Note: The LOGICAL data type is typedef'ed in MFLDEFS.H.
STRALLOC_OK grants permission for stralloc() to
resize any existing string should it be shorter
than requested. To avoid this situation, you
may pre-allocate all the strings in the pool to
a specified size using str_init(), below.
DESCRIPTION
This function supports the BASIC-like string functions. The
underlying function is stralloc() which maintains a pool of character
buffers which it dispenses as requested and constantly reuses and
reallocates as required. As a default, stralloc maintains a circular
buffer of 16 strings in Tiny, Small, and Medium models and 64 strings
in Compact and Large models. These start out very small and grow as
required. Should you wish to expand the number of strings or wish to
pre-allocate strings of a given minimum size to avoid re- allocation,
the str_init() function allows setting both parameters.
Since the strings are allocated from a circular buffer, if these
routines are used within a recursive routine, it is strongly
recommended that their results be copied (using strcpy() or strdup())
into their own dedicated space. If the result is copied into a
malloc'ed string which subsequently is free'd, you should
pre-allocate the string pool using str_init(), as noted above.
EXAMPLE
char *a;
a = stralloc(MAX_FLEN);
/* Grabs reusable string space large enough for a filename */
SEE ALSO: str_init(), str_free()
STREQ.FNC - Thu 23 Nov 89 00:20 - Page 220:
NAME
STREQ -- compares strings TRUE/FALSE
DEFINED IN: mflstrng.h
SYNOPSIS
r = STREQ(s1,s2);
LOGICAL r; TRUE if strings match, else FALSE
char *s1,*s2; strings to compare
DESCRIPTION
This is one of the macros included in MFLSTRNG.H. The STREQ and STREQI
macros are simply aliases to encapsulate strcmp() and strcmpl() so
the return is inverted from its normal sense.
EXAMPLES
char *string1, string2;
if (STREQ(string1,string2))
puts("the strings match");
else pust("no match, but it reads more logically");
SEE ALSO: STREQI()
STREQI.FNC - Thu 23 Nov 89 00:20 - Page 221:
NAME
STREQI -- compares strings TRUE/FALSE, UC/LC
PROTOTYPED IN: mflstrng.h
SYNOPSIS
r = STREQI(s1,s2);
LOGICAL r; TRUE if strings match, else FALSE. Case is
ignored.
char *s1,*s2; strings to compare
DESCRIPTION
This one of the macros included in MFLSTRNG.H. The STREQ and STREQI
macros are simply aliases to encapsulate strcmp() and strcmpl() so the
return is inverted from its normal sense.
EXAMPLES
char *string1, string2;
if (STREQI(string1,string2))
puts("the strings match");
else pust("no match, but it reads more logically");
SEE ALSO: STREQ()
STRFTIME.FNC - Thu 23 Nov 89 00:20 - Page 222:
NAME
strftime -- convert data in tm structure to a string
PROTOTYPED IN: mfltime.h
PORTABILITY: ANSI - strftime() is fully compliant including locale
support
SYNOPSIS
r = strftime(buf,siz,fmt,tim);
int r; length of the formatted string
char *buf; buffer to receive the formatted string
int siz; size of the buffer
struct tm *tim; date/time data to format
DESCRIPTION
The strftime() function is defined in the ANSI draft but rarely
implemented. It is like a printf() for time and date information.
Country-specific formatting information may be specified - see
setlocale().
The conversion characters supported by strftime() are:
%a 3-character abbreviated weekday, e.g. Thu
%A weekday name, e.g. Thursday
%b 3-character abbreviated month, e.g. Jul
%B month name, e.g. July
%c standard format, e.g. Jul 13 14:27:39 1989
%d day of the month (01-31)
%H hour of the day (00-23)
%I hour of the day (01-12)
%j day of the year (001-365)
%m month (01-12)
%M minutes (00-59)
%p AM/PM indicator, e.g. PM
%S seconds (01-59)
%U week (starting Sundays) of the year (01-53)
%w weekday (0-6, Sunday = 0)
%W week (starting Mondays) of the year (01-53)
%x date, e.g. Jul 13 1989
%X time, e.g. 13:27:39
%y year (00-99)
%Y year with century (1970-2069)
%Z time zone (from TZ_txt & DST_flag), e.g. CST
%% literal '%' character
STRFTIME.FNC - Thu 23 Nov 89 00:20 - Page 223:
EXAMPLE
#include <locale.h>
extern struct LOC_TIME *loc_time;
char buf[81];
setlocale(LC_TIME, "C"); /* set defaults */
strftime(buf, 80, "%A %c (day %j)", t);
/* buf = "Thursday Jul 13 14:27:39 1989 (day 194)" */
strftime(buf, 80, "%A, %B %d, %Y, %I:%M:%S %P %z", t);
/* buf = "Thursday, July 13, 1989, 02:27:39 PM CST" */
loc_time->TZ_txt = {"MST", "MDT"};
loc_time->DST_flag = 1;
strftime(buf, 80, "%d %b %y (%a) %H:%M:%S %z", t);
/* buf = "13 Jul 89 (Thu) 14:27:39 MDT" */
SEE ALSO: set_locale(), localeconv(), tzset()
STRIP.FNC - Thu 23 Nov 89 00:20 - Page 224:
NAME
strip -- strip a newline from a string
PROTOTYPED IN: mflstrng.h
SYNOPSIS
void strip(str);
char *str;
DESCRIPTION
If the specified string terminates with a newline (\n) character, this
function will replace the character with a NULL.
EXAMPLE
char str[] = "This is a string\n";
strip(str);
the newline is stripped from str
STRIXLAT.FNC - Thu 23 Nov 89 00:20 - Page 225:
NAME
strixlat -- translates characters based on tables
PROTOTYPED IN: mflstrng.h
SYNOPSIS
r = strixlat(str,old,new);
int r; number of characters changed, ERROR if
size of `old' doesn't match size of `new'
char *old; characters to change, case ingonred
char *new; translated characters, case preserved
DESCRIPTION
This function replaces all occurrences of characters found in an input
string and contained in a translation string to corresponding
characters from a second translation string.
EXAMPLE
char *str="ABCxyzPpPpRrRr";
strxlat(str,"abc","1234"); /* returns ERROR */
strxlat(str,"XYZabc","xyzABC"); /* returns zero */
strxlat(str,"xyzABC","MNOdef"); /* "defMNOPpPpRrRr" */
strixlat(str,"pr","ST"); /* "defMNOSsSsTtTt" */
strnixlat(str,"mno","ghi",2); /* "defGHOSsSsTtTt" */
SEE ALSO: strxlat(), strnxlat(), strnixlat()
STRNIXLT.FNC - Thu 23 Nov 89 00:20 - Page 226:
NAME
strnixlat -- translates first N characters based on tables
PROTOTYPED IN: mflstrng.h
SYNOPSIS
r = strnixlat(str,old,new,n);
int r; number of characters changed, ERROR if
size of `old' doesn't match size of `new'
char *old; characters to change, case ingonred
char *new; translated characters, case preserved
int n; translate first `n' occurances
DESCRIPTION
This function replaces the first N occurances of characters found in
an input string and contained in a translation string to corresponding
characters from a second translation string.
EXAMPLE
char *str="ABCxyzPpPpRrRr";
strxlat(str,"abc","1234"); /* returns ERROR */
strxlat(str,"XYZabc","xyzABC"); /* returns zero */
strxlat(str,"xyzABC","MNOdef"); /* "defMNOPpPpRrRr" */
strixlat(str,"pr","ST"); /* "defMNOSsSsTtTt" */
strnixlat(str,"mno","ghi",2); /* "defGHOSsSsTtTt" */
SEE ALSO: strxlat(), strnxlat(), strixlat()
STRNXLAT.FNC - Thu 23 Nov 89 00:20 - Page 227:
NAME
strnxlat -- translates first N characters based on tables
PROTOTYPED IN: mflstrng.h
SYNOPSIS
r = strnxlat(str,old,new,count);
int r; number of characters changed, ERROR if
size of `old' doesn't match size of `new'
char *old; characters to change
char *new; translated characters
int n; translate first `n' occurances
DESCRIPTION
This function replaces the first N occurances of characters found in
an input string and contained in a translation string to corresponding
characters from a second translation string.
EXAMPLE
char *str="ABCxyzPpPpRrRr";
strxlat(str,"abc","1234"); /* returns ERROR */
strxlat(str,"XYZabc","xyzABC"); /* returns zero */
strxlat(str,"xyzABC","MNOdef"); /* "defMNOPpPpRrRr" */
strixlat(str,"pr","ST"); /* "defMNOSsSsTtTt" */
strnixlat(str,"mno","ghi",2); /* "defGHOSsSsTtTt" */
SEE ALSO: strxlat(), strixlat(), strnixlat()
STRXLAT.FNC - Thu 23 Nov 89 00:20 - Page 228:
NAME
strxlat -- translates characters based on tables
PROTOTYPED IN: mflstrng.h
SYNOPSIS
r = strxlat(str,old,new);
int r; number of characters changed, ERROR if
size of `old' doesn't match size of `new'
char *old; characters to change
char *new; translated characters
DESCRIPTION
This function replaces all occurances of characters found in an input
string and contained in a translation string to corresponding
characters from a second translation string.
EXAMPLE
char *str="ABCxyzPpPpRrRr";
strxlat(str,"abc","1234"); /* returns ERROR */
strxlat(str,"XYZabc","xyzABC"); /* returns zero */
strxlat(str,"xyzABC","MNOdef"); /* "defMNOPpPpRrRr" */
strixlat(str,"pr","ST"); /* "defMNOSsSsTtTt" */
strnixlat(str,"mno","ghi",2); /* "defGHOSsSsTtTt" */
SEE ALSO: strnixlat(), strnxlat(), strixlat()
STUFF.FNC - Thu 23 Nov 89 00:20 - Page 229:
NAME
stuff -- get equipment report (high level)
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = _stuff(kind);
int r; result of test
int kind; kind of equipment to test for
DESCRIPTION
This function calls _stuff() and checks the appropriate
bits returned depending upon the kind of information
requested. Kind is one of the following:
0 = initial video mode
mode 0, 2, or 7 returned
1 = number of disk drives
2 = number of printers
3 = number of serial ports
4 = joystick installed
EXAMPLE
int r;
r = stuff(0);
if(r == 7) printf("Monochrome card installed");
TIME2JUL.FNC - Thu 23 Nov 89 00:20 - Page 230:
NAME
time_to_julian -- convert time_t value to Julian date
PROTOTYPED IN: mfltime.h
SYNOPSIS
r = time_to_julian(time);
long r; Julian (scalar) date
time_t time; date/time to convert
DESCRIPTION
This function converts date and time information, as expressed in
standard time_t data types, to scalar (Julian) dates. Only the date
information is preserved, the time is lost.
EXAMPLE
long jday;
time_t tim;
/* Get today's date */
jday = time_to_julian(time(&tim));
SEE ALSO: julian_to_ymd(), julian_to_wkday(), julian_to_yrday(),
julian_to_dayname(), julian_to_time(), julian_to_tm(),
ymd_to_julian(), tm_to_julian
TM2JUL.FNC - Thu 23 Nov 89 00:20 - Page 231:
NAME
tm_to_julian -- convert tm structure to Julian date
PROTOTYPED IN: mfltime.h
SYNOPSIS
r = tm_to_julian(t);
long r; Julian (scalar) date
struct tm *t; date/time data to convert
DESCRIPTION
This function converts date and time information, as included in
standard tm structure, to scalar (Julian) dates. Only the date
information is preserved, the time is lost.
EXAMPLE
long jday;
time_t tim;
struct tm *t;
/* Get today's date */
time(&tim);
jday = time_to_julian(localtime(&tim));
SEE ALSO: julian_to_ymd(), julian_to_wkday(), julian_to_yrday(),
julian_to_dayname(), julian_to_time(), julian_to_tm(),
ymd_to_julian(), time_to_julian
TOUCH.FNC - Thu 23 Nov 89 00:20 - Page 232:
NAME
touch -- set file time/date stamp to the current time
PROTOTYPED IN: mfltime.h
PORTABILITY: Unix
SYNOPSIS
r = touch(file);
int r; returns 0 if successful, else -1
char *file; file to set to curreent date & time
DESCRIPTION
The touch() function is similar to the unix command of the same name.
Passed a file name, touch() sets its time/date stamp to the current
time and date.
EXAMPLE
if (ERROR == touch("file.ext"))
puts("couldn't update time/date stamp");
SEE ALSO: setftime()
TRUNC.FNC - Thu 23 Nov 89 00:20 - Page 233:
NAME
trunc -- truncate an open'ed file
PROTOTYPED IN: mflfiles.h
SYNOPSIS
result = trunc(fd,posn);
int result; SUCCESS or ERROR
int fd; handle of file to truncate
long posn; size of truncated file
DESCRIPTION
The trunc() function will truncate a file that has been opened using the
file handle open() call. It will return an ERROR if the truncation length
is longer than the existing file.
EXAMPLE
int fd;
FILE *fp;
char *fname[] = {"file1","file2","file3"};
long sizes[] = 100L, 200L, 300L;
fd = open(fname[0], O_WRONLY);
fp = fopen(fname[1], "wb");
trunc(fd, sizes[0]);
ftrunc(fp, sizes[1]);
truncate(fname[2], sizes[2]);
SEE ALSO: truncate(), ftrunc()
TRUNCATE.FNC - Thu 23 Nov 89 00:20 - Page 234:
NAME
truncate -- truncate a named file
PROTOTYPED IN: mflfiles.h
SYNOPSIS
result = truncate(fname,posn);
int result; SUCCESS or ERROR
char *fname; name of file to truncate
long posn; size of truncated file
DESCRIPTION
This is one of the MFLIB routines which provide three different
methods for truncating files to a given length - by name, handle or
descriptor. They all work identically except that truncate() will
check and return an ERROR if the truncation length is longer than the
existing file.
EXAMPLE
int fd;
FILE *fp;
char *fname[] = {"file1","file2","file3"};
long sizes[] = 100L, 200L, 300L;
fd = open(fname[0], O_WRONLY);
fp = fopen(fname[1], "wb");
trunc(fd, sizes[0]);
ftrunc(fp, sizes[1]);
truncate(fname[2], sizes[2]);
SEE ALSO: ftrunc(), trunc()
UCASFILT.FNC - Thu 23 Nov 89 00:20 - Page 235:
NAME
ucase_filt -- a filter to force streams to upper case
DECLARED IN: mflfiles.h
SYNOPSIS
r = sfinstall(stream,ucase_filt);
int r; SUCCESS or ERROR
SFILE *stream; stream to be filtered
DESCRIPTION
Not a function, ucase_filt is an SFILTER structure used with sfinstall()
to force streams to upper case.
EXAMPLE
SFILE *infile;
infile = sfopen("file.ext", "r"); /* input from a file */
crypt_install(infile, "keytxt", 0); /* encrypt using "keytxt" */
sfinstall(infile, ucase_filt); /* after converting to UC */
SEE ALSO: sfopen(), scopen(), sclose(), sfinstall(), crypt_install(),
lcase_filt
UNIX2DOS.FNC - Thu 23 Nov 89 00:20 - Page 236:
NAME
unix2dos -- converts Unix-style paths to DOS-style
PROTOTYPED IN: mflfiles.h
SYNOPSIS
path = unix2dos(path);
char *path; pathname to convert
DESCRIPTION
unix2dos() converts Unix-style filenames (i.e. using the "/" character
as a path separator) to DOS-style.
EXAMPLE
puts(unix2dos("unix_dos/style/path/name.ext"));
/* Prints "UNIX_DOS\STYLE\PATH\NAME.EXT" */
SEE ALSO: flnorm(), fln_fix()
USECCLK.FNC - Thu 23 Nov 89 00:20 - Page 237:
NAME
usec_clock -- read the system clock in microseconds
PROTOTYPED IN: mfltime.h
SYNOPSIS
t = usec_clock();
uclock_t r; returns zero if first call, thereafter
returns microseconds elapsed
DESCRIPTION
This is one of a group of timing functions with an accuracy of one
microsecond on IBM and closely compatible computers. To function
properly, these functions require the host system to use either an
8253 or 8254 counter/timer chip based at I/O address 40h to generate
the 18.2 Hz system interrupt used by DOS. These functions further
assume that DOS uses the four bytes at 40:6C for its timekeeping
function. These have proven to be safe assumptions for all IBM PC's
and PS/2's, Compaq's, as well as most other clone computers and
single-board computers designed for MS/PC-DOS compatibility. The sole
exception is msec_pause() which requires the counter/timer chip but
makes no other assumptions.
The key function is usec_clock() which is a microsecond-accurate
replacement for the normal clock() function. Just as the time
returned by clock() may be converted to seconds by dividing by
CLK_TCK, values returned by usec_clock may be similarly converted
by dividing by UCLK_TCK, defined in MFLSYS.H.
The usec_clock() function relies on data which rolls over at
midnight each day and can handle this. However, if a program is to
run continuously for many days, it becomes necessary to take
action to prevent internal overflow. This may be done by resetting
the internal registers used by usec_clock() at least once per day
by calling restart_uclock().
USECCLK.FNC - Thu 23 Nov 89 00:20 - Page 238:
EXAMPLE
uclock_t time_1, time_2;
int i;
time_1 = usec_clock(); /* take an initial clock reading */
for (i = 1; i < 1000; ++i)
{
/* do things here but we don't know for how long */
}
time_2 = usec_delay(500000L); /* pause 0.5 sec, note time */
do {
/* do things here for 1.2345 seconds */
if (5000000L > usec_difftime(usec_clock() - time_1))
break; /* abort if total time is over 5 sec. */
} while (!timeout(time_2, usec_clock(), 1234500L));
SEE ALSO: restart_uclock(), usec_delay(), usec_difftime(),
usec_timeout(), msec_pause()
USECDIFF.FNC - Thu 23 Nov 89 00:20 - Page 239:
NAME
usec_difftime -- calculate the difference between two times
DEFINED IN: mfltime.h
SYNOPSIS
diff = usec_difftime(start, end);
uclock_t diff; microseconds elapsed between start & end
uclock_t start; start time (from usec_clock())
uclock_t end; ending time (from usec_clock())
DESCRIPTION
This is part of a set of timing functions with an accuracy of one
microsecond on IBM and closely compatible computers. The key function is
usec_clock() which is a microsecond-accurate replacement for the normal
clock() function. Just as the time returned by clock() may be converted
to seconds by dividing by CLK_TCK, values returned by usec_clock may be
similarly converted by dividing by UCLK_TCK, defined in MFLTIME.H.
Two differential time functions are provided; usec_difftime(), a macro
which simply returns the difference between two usec_clock() readings,
and usec_timeout() which tests for an expired time limit.
EXAMPLE
uclock_t time_1, time_2;
int i;
time_1 = usec_clock(); /* take an initial clock reading */
for (i = 1; i < 1000; ++i)
{
/* do things here but we don't know for how long */
}
time_2 = usec_delay(500000L); /* pause 0.5 second, note time */
do {
/* do things here for 1.2345 seconds */
if (5000000L > usec_difftime(usec_clock() - time_1))
break; /* abort if total time is over 5 sec. */
} while (!timeout(time_2, usec_clock(), 1234500L));
SEE ALSO: restart_uclock(), usec_clock(), usec_delay(),
usec_timeout(), msec_pause()
USECDLY.FNC - Thu 23 Nov 89 00:20 - Page 240:
NAME
usec_delay -- delay a given number of microseconds
PROTOTYPED IN: mfltime.h
SYNOPSIS
end = usec_delay(usec);
uclock_t end; usec_clock() value at end of delay
uclock_t usec; number of microseconds to delay
DESCRIPTION
This part of a set of timing functions with an accuracy of one
microsecond on IBM and closely compatible computers. To function
properly, these functions require the host system to use either an
8253 or 8254 counter/timer chip based at I/O address 40h to generate
the 18.2 Hz system interrupt used by DOS. These functions further
assume that DOS uses the four bytes at 40:6C for its timekeeping
function. These have proven to be safe assumptions for all IBM PC's
and PS/2's, Compaq's, as well as most other clone computers and
single-board computers designed for MS/PC-DOS compatibility. The sole
exception is msec_pause() which requires the counter/timer chip but
makes no other assumptions.
Two delay functions are provided; usec_delay() which is passed a
number of microseconds, and msec_pause() which is passed a number
of milliseconds. Other than the time units, one difference between
the two is that msec_pause() is slightly more portable as noted
above. Another difference is that usec_delay() returns the value
returned by usec_clock() when it finished. This is done in order
to be able to chain time measurements.
EXAMPLE
uclock_t time_1, time_2;
int i;
time_1 = usec_clock(); /* take an initial clock reading */
for (i = 1; i < 1000; ++i)
{
/* do things here but we don't know for how long */
}
time_2 = usec_delay(500000L); /* pause 0.5 second, note time */
do {
/* do things here for 1.2345 seconds */
if (5000000L > usec_difftime(usec_clock() - time_1))
break; /* abort if total time is over 5 sec. */
} while (!timeout(time_2, usec_clock(), 1234500L));
SEE ALSO: restart_uclock(), usec_clock(), usec_difftime(),
usec_timeout(), msec_pause()
USECTOUT.FNC - Thu 23 Nov 89 00:20 - Page 241:
NAME
usec_timeout -- test for a timeout condition
PROTOTYPED IN: mfltime.h
SYNOPSIS
stat = usec_timeout(start, end, usecs);
LOGICAL stat; TRUE if time limit exceeded, else FALSE
uclock_t start; start time (from usec_clock())
uclock_t end; ending time (from usec_clock())
uclock_t usecs; time limit in microseconds
DESCRIPTION
This is part of a set of timing functions with an accuracy of one
microsecond on IBM and closely compatible computers. The key function is
usec_clock() which is a microsecond-accurate replacement for the normal
clock() function. Just as the time returned by clock() may be converted
to seconds by dividing by CLK_TCK, values returned by usec_clock may be
similarly converted by dividing by UCLK_TCK, defined in MFLTIME.H.
Two differential time functions are provided; usec_difftime(), a macro
which simply returns the difference between two usec_clock() readings,
and usec_timeout() which tests for an expired time limit.
EXAMPLE
uclock_t time_1, time_2;
int i;
time_1 = usec_clock(); /* take an initial clock reading */
for (i = 1; i < 1000; ++i)
{
/* do things here but we don't know for how long */
}
time_2 = usec_delay(500000L); /* pause 0.5 second, note time */
do {
/* do things here for 1.2345 seconds */
if (5000000L > usec_difftime(usec_clock() - time_1))
break; /* abort if total time is over 5 sec. */
} while (!timeout(time_2, usec_clock(), 1234500L));
SEE ALSO: restart_uclock(), usec_clock(), usec_difftime(),
usec_timeout(), msec_pause()
VIDBORDR.FNC - Thu 23 Nov 89 00:20 - Page 242:
NAME
vid_border -- set border color
PROTOTYPED IN: mflconio.h
SYNOPSIS
(void) vid_border(clr);
int clr; one of the 16 color values
DESCRIPTION
This function and vid_palette manipulate the CGA card, or EGA card in
CGA color mode. vid_border() sets the border color outside the
normal text area to any of the 16 possible colors.
vid_palette() sets the working color palette, and has meaning
only in CGA mode 4 (color 320 x 200).
palette # colors 0, 1, 2, 3
0 background, green, red, brown
1 background, cyan, magenta, white
Call vid_palette() before using the vid_wrpix() function.
In black&white 640 x 200 graphics mode, vid_border() will set
the foreground color used for the display. The background
will always be black.
EXAMPLE
vmode(CG320); /* set 320 color graphics mode */
vid_border(BLUE); /* set border and graphics background color */
vid_palette(1); /* select palette 1 */
vid_wrpix(10, 10, 2) /* write a pixel at x10, y10, color 2,
which is magenta in palette 1 */
SEE ALSO: vid_palette()
VIDPAGE.FNC - Thu 23 Nov 89 00:20 - Page 243:
NAME
vidpage -- set a video page as active page
PROTOTYPED IN: mflconio.h
SYNOPSIS
void vidpage(page);
int page; 0-7 depending upon mode
DESCRIPTION
This function sets the video display page to any page 0-7 subject to
the effective video mode. Note that the monochrome card does not
support video pages and therefore this function will have no effect.
EXAMPLE
vidpage(0); default lowest page
VIDPALET.FNC - Thu 23 Nov 89 00:20 - Page 244:
NAME
vid_palette -- set color palette
PROTOTYPED IN: mflconio.h
SYNOPSIS
(void) vid_palette(num);
int clr; one of the 16 color values
int num; palette 0 or 1
DESCRIPTION
This function and vid_border() manipulate the CGA card, or EGA card in
CGA color mode. vid_border() sets the border color outside the normal
text area to any of the 16 possible colors. vid_palette() sets the
working color palette, and has meaning only in CGA mode 4 (color 320 x
200).
palette # colors 0, 1, 2, 3
0 background, green, red, brown
1 background, cyan, magenta, white
Call vid_palette() before using the vid_wrpix() function. In
black&white 640 x 200 graphics mode, vid_border() will set the
foreground color used for the display. The background will always be
black.
EXAMPLE
vmode(CG320); /* set 320 color graphics mode */
vid_border(BLUE); /* set border and graphics background color */
vid_palette(1); /* select palette 1 */
vid_wrpix(10, 10, 2) /* write a pixel at x10, y10, color 2,
which is magenta in palette 1 */
SEE ALSO: vid_border()
VIDRDPIX.FNC - Thu 23 Nov 89 00:20 - Page 245:
NAME
vid_rdpix -- read a pixel from the screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
(void) vid_rdpix(x, y, clr);
int x, y; x and y screen coordinates
int clr; one of the 4 color values for current palette
DESCRIPTION
This function and vid_wrpix() manipulate the CGA card, or EGA card in
CGA graphics mode. vid_wrpix() will set the pixel at location x,y to
the color clr, which is 0, 1, 2, or 3. The real color will be as set
via vid_palette(). For black and white 640 graphics, use 0 or 1 only.
vid_rdpix() will return the color value (0-3) at the specified x,y
location. If using black&white 640 x 200 graphics mode on a CGA, then
the color value for vid_wrpix should be 0 or 1. 0 will set the pixel
to black (which is the background color), and 1 will set the pixel to
the color which has been previously selected by vid_border() (the
default is, of course, white). In BW640 mode, therefore, the pixels
can only be turned on or off. There is no possibility of multi-color
displays. These functions do not support the extra modes of the EGA or
PGA adapters.
EXAMPLE
vmode(CG320); /* set 320 color graphics mode */
vid_border(BLUE); /* set border and graphics background color */
vid_palette(1); /* select palette 1 */
vid_wrpix(10, 10, 2) /* write a pixel at x10, y10, color 2,
which is magenta in palette 1 */
SEE ALSO: vid_rdpix()
VIDWRPIX.FNC - Thu 23 Nov 89 00:20 - Page 246:
NAME
vid_wrpix -- write a pixel to the screen
PROTOTYPED IN: mflconio.h
SYNOPSIS
(void) vid_wrpix(x, y, clr);
int x, y; x and y screen coordinates
int clr; one of the 4 color values for current palette
DESCRIPTION
This function and vid_rdpix() manipulate the CGA card, or EGA card in
CGA graphics mode. vid_wrpix() will set the pixel at location x,y to
the color clr, which is 0, 1, 2, or 3. The real color will be as set
via vid_palette(). For black and white 640 graphics, use 0 or 1 only.
vid_rdpix() will return the color value (0-3) at the specified x,y
location. If using black&white 640 x 200 graphics mode on a CGA, then
the color value for vid_wrpix should be 0 or 1. 0 will set the pixel
to black (which is the background color), and 1 will set the pixel to
the color which has been previously selected by vid_border() (the
default is, of course, white). In BW640 mode, therefore, the pixels
can only be turned on or off. There is no possibility of multi-color
displays. These functions do not support the extra modes of the EGA or
PGA adapters.
EXAMPLE
vmode(CG320); /* set 320 color graphics mode */
vid_border(BLUE); /* set border and graphics background color */
vid_palette(1); /* select palette 1 */
vid_wrpix(10, 10, 2) /* write a pixel at x10, y10, color 2,
which is magenta in palette 1 */
SEE ALSO: vid_rdpix()
VINIT.FNC - Thu 23 Nov 89 00:20 - Page 247:
NAME
v_init -- obtains information on the video system
PROTOTYPED IN: mflconio.h
SYNOPSIS
v_init();
DESCRIPTION
The v_init() function analyzes the video system and filles in the global
structure, v_info_, defined in MFLCONIO.H. Included in this structure are
fields containing the following information:
o The number of rows displyable on the active display
o The number of columns displyable on the active display
o The video mode of the active display
o The active page of the active display
o The screen segment of the active display
o The screen address of the active display
o A flag to signal if DesqView or TopView is active
EXAMPLE
v_init();
printf("displaying %d rows by %d cols\n",
v_info_.rows, v_info_.cols);
VISCROLL.FNC - Thu 23 Nov 89 00:20 - Page 248:
NAME
viscroll -- scrolls the video display up or down
PROTOTYPED IN: mflconio.h
PORTABILITY: Compatible with Blaise (tm) library function of the same
name.
SYNOPSIS
void viscroll(lines,atr,tlrow,tlcol,brrow,brcol,dir);
int lines; number of lines to scroll
int atr; video attribute of new lines
int tlrow; top left row
int tlcol; top left column
int brrow; bottom right row
int brcol; bottom right column
int dir; direction (SCR_UP or SCR_DN)
DESCRIPTION
The viscroll() function calls the BIOS video routines to directly
scroll an area of the screen. The area to be scrolled is defined
as a rectangular block whose upper left and bottom right co-
ordinates are passed to viscroll(). As lines are scrolled, new
ones appear to take their place whose video attribute is also
specified. Finally, the direction to scroll is specified using the
macro definitions SCR_UP and SCR_DN. If passed zero for the number
of lines to scroll, the specified area is cleared to the specified
attribute, acting like a windowed version of d_cls().
EXAMPLE
viscroll(2,NORMAL,0,0,7,79,SCR_UP); /* scroll top 1/3 up 2 */
viscroll(0,REVERSE,8,0,15,79,SCR_UP); /* clear middle 1/3 */
viscroll(2,NORMAL,16,0,23,79,SCR_DN); /* scroll btm 1/3 dn 2 */
VMODE.FNC - Thu 23 Nov 89 00:20 - Page 249:
NAME
vmode -- set video mode
PROTOTYPED IN: mflconio.h
SYNOPSIS
void vmode(mode);
int mode;
DESCRIPTION
This function sets the video mode from 0 - 7. Modes are as specified
in the DOS manual. The most common is Black & White 80 column mode,
which is mode 2. This library package includes screen.h which defines
video modes.
EXAMPLE
#include <screen.h>
vmode(BW80);
WEEKDAY.FNC - Thu 23 Nov 89 00:20 - Page 250:
NAME
weekday -- Determine the day of the week form the date
PROTOTYPED IN: mfltime.h
SYNOPSIS
value = weekday(month, day, year);
int value; returns 0-6
int month; number of month 1-12
int day; number of date 1-31
int year; year starting with 1980
DESCRIPTION
This function returns the number of the day in the week for any
date from January 1, 1980. Sunday is day 0, and Saturday is day 6.
EXAMPLE
for July 2, 1986:
int value;
value = weekday(7, 2, 1986);
value for this date will be 3 (Wednesday)
You may wish me a Happy Birthday.
SEE ALSO: julian_to_dayname(), julian_to_wkday()
WILDNAME.FNC - Thu 23 Nov 89 00:20 - Page 251:
NAME
wildname -- matches filenames against a pattern
PROTOTYPED IN: mflfiles.h
SYNOPSIS
r=wildname(pat, str, rule);
int r; zero if match, else non-zero
char *pat; pattern to match - may contain wildcards
char *str; filename to match
int rule; universal wildcard rules - may be:
0 - no universal wildcards
DOS_STYLE - "." matches anything
UNIX_STYLE - "*" matches anything
BOTH_STYLES - "*", or "." match anything
DESCRIPTION
There are times when you need to manually perform a wildcard
pattern match on a filename rather than let DOS do it for you.
There also times when you'd like the pattern matching to be a
little smarter than DOS's. The wildname() function performs both
services. Passed a pattern and a filename (no path or directory
specs allowed, though), it will return a value similar to strcmp()
if the filename matches the pattern. It is also smart enough to
properly handle embedded '*' wildcards which DOS can't do. A '?'
wildcard will match any character. A '*' wildcard may match zero
or more occurances of any character(s). Optionally, wildname()
allows either, both or neither DOS or Unix-style unversal pattern
matching. The universal DOS pattern is "." and will match any file
name. The universal Unix pattern is "*". The implicit universal
pattern is "*.*" and will match any file name regardless of which
style (if any) universal pattern is selected. Finally, note that
if DOS style pattern matching is specified, the smart "*" wildcard
pattern matching is disabled in order to fully emulate DOS's brain
damaged wildcard processing.
WILDNAME.FNC - Thu 23 Nov 89 00:20 - Page 252:
EXAMPLES
wildname("A*C.E?T", "ABC.EXT", 0); /* matches */
wildname("A*C.E?T", "ABX.EXT", 0); /* no match */
wildname("A*C.E?T", "ALEC.EXT", 0);/* matches */
wildname("A*C.E?T", "ABC.ET", 0); /* no match */
wildname("A*C.E*T", "ABC.ET", 0); /* matches */
wildname("*.*", "ABC.XYZ", 0); /* matches */
wildname(".", "ABC.XYZ", 1); /* matches */
wildname("*", "ABC.XYZ", 2); /* matches */
wildname(".", "ABC.XYZ", 3); /* matches */
wildname("*", "ABC.XYZ", 3); /* matches */
wildname("A*C.X*Z", "ABZ.XYC", 0); /* no match */
wildname("A*C.X*Z", "ABZ.XYC", 1); /* matches */
wildname("A*C.X*Z", "ABZ.XYC", 2); /* no match */
wildname("A*C.X*Z", "ABZ.XYC", 3); /* no match */
SEE ALSO: dirmask()
WKDAYNM.FNC - Thu 23 Nov 89 00:20 - Page 253:
NAME
wkdayname -- return a pointer to name of day string
PROTOTYPED IN: mfltime.h
SYNOPSIS
char *wkdayname(day);
int day; day number 0-6
DESCRIPTION
This function returns a character pointer to a text string naming the
day of the week indicated by the day parameter. Day 0 is Sunday, and
day 6 is Saturday. Strings are null terminated and may be used
directly or copied to another string.
EXAMPLE
printf("Today is %s", wkdayname(3));
/* output is :
Today is Wednesday
*/
WRTCHAR.FNC - Thu 23 Nov 89 00:20 - Page 254:
NAME
writechar -- send a char to the serial port
PROTOTYPED IN: mflsys.h
SYNOPSIS
(void) writechar(port, r);
unsigned char r; character to send or receive
int port; port number
DESCRIPTION
This is part of some very low level (direct port access) subroutines
included to enable I/O through COM1 through COM4. Only setport() uses
BIOS int 14H. These functions are not intended to be the ultimate in
async functions, but a starting point for an integrated set of async
functions, and a means of getting at the serial port directly for
speed and to work around the problems that some "clone" BIOS routines
have in returning proper status values. File "MFLDEFS.H" contains
#defines to handle these ports mnemonically.
writechar() will place the specified unsigned char into the
transmitter buffer register where it will be sent.
If the program "loop" is short and fast enough, these functions will
be ample to allow communications at up to 9600 baud. A program has
already been implemented to communicate with a prom programmer at this
rate, so it can be done. However, when the program does not poll the
receiver fast enough it is likely that characters may be lost and the
maximum usable baud rate will be lower. It is highly unlikely that
baud rates less than 2400 baud will be necessary if the program is
properly structured.
EXAMPLE
/* this routine receives characters from COM1 at one
** speed and resends them to COM2 at another speed */
unsigned char i;
setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity,
** 8-bits, 1 stop bit */
setport(SER2, 0xc3); /* set COM2 the same, except 4800 baud */
while(TRUE) {
if(!ready_rcv(SER1)) continue; /* wait for a char */
i = readchar(SER1); /* fetch it */
while(!ready_xmt(SER2));/* wait for transmitter to be ready */
writechar(SER2, i); /* then send it */
}
SEE ALSO: readchar(), ready_rcv(), ready_xmt(), setport()
YMD2JUL.FNC - Thu 23 Nov 89 00:20 - Page 255:
NAME
ymd_to_julian -- convert year, month, date to Julian date
PROTOTYPED IN: mfltime.h
SYNOPSIS
r = ymd_to_julian(yr,mo,day);
long r; Julian (scalar) date
unsigned yr; year
unsigned mo; month
unsigned day; date
DESCRIPTION
This function converts dates expressed in days, months, and years
into scalar (Julian) dates.
EXAMPLE
long jday;
jday=ymd_to_julian(1974,6,9);
SEE ALSO: julian_to_ymd(), julian_to_wkday(), julian_to_yrday(),
julian_to_dayname(), julian_to_time(), julian_to_tm(),
time_to_julian(), tm_to_julian
_GETDI.FNC - Thu 23 Nov 89 00:20 - Page 256:
NAME
_getdi -- get device information for file handle
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = _getdi(fh);
int r; status byte, low 8 bits only
int fh; DOS file handle to investigate
DESCRIPTION
This function returns the lower 8 bits of the control word for the
specified file handle, usually stdout, stdin, or one of the other
standard channels. Note that a file handle, NOT file descriptor is
required. Refer to the DOS manual for the description of all the
bits. Bit 7 set indicates a character device, and bits 0,1 refer to
the console. This function is called by the functions isatty() and
iscons().
EXAMPLE
int r;
int fh;
fh = fileno(stdout); /* get file handle for stdout */
r = _getdi(fh);
if(r >= 0x80) printf("stdout is a character device");
_STUFF.FNC - Thu 23 Nov 89 00:20 - Page 257:
NAME
_stuff -- get equipment report (low level)
PROTOTYPED IN: mflsys.h
SYNOPSIS
r = _stuff();
int r;
DESCRIPTION
Returns an integer from DOS int 11H, indicating the
available equipment and initial video mode. This
is a low level function. For a higher level function,
refer to stuff().
bits 15, 14 = # of printers installed
bit 12 = joystick installed if 1
bits 11-9 = # of serial ports installed
bits 7-6 = # of disk drives, 1-4 if bit 0 = 1
bits 5-4 = Initial video mode:
01 40 x 25 b/w CGA
10 80 x 25 b/w CGA
11 80 x 25 Mono card
bit 0 = no disk drives if 0
EXAMPLE
int r;
r = _stuff();
/* test bit 12 (game port) */
if((r & 0x1000) != 0) printf("Game port installed");